Second cleanup of multiline editing patch. Add code comments, use better variable names, etc..

darcs-hash:20061001212243-ac50b-6cd5abfcf6b7013fd23b27734ca29af27d945ca3.gz

1 files changed, 64 insertions, 11 deletions

diff --git a/screen.h b/screen.h
index 0ae93db2..fa5e3291 100644
--- a/screen.h
+++ b/screen.h
@@ -1,34 +1,87 @@
+/** \file screen.h High level library for handling the terminal screen
+
+	The screen library allows the interactive reader to write its
+	output to screen efficiently by keeping an inetrnal representation
+	of the current screen contents and trying to find the most
+	efficient way for transforming that to the desired screen content.
+*/
 #ifndef FISH_SCREEN_H
 #define FISH_SCREEN_H
 
-#define SCREEN_REPAINT 1
-#define SCREEN_SKIP_RETURN 2
-
+/**
+   The struct representing the current and desired screen contents.
+*/
 typedef struct
 {
-	array_list_t output;
-	array_list_t screen;
-	int output_cursor[2];
-	int screen_cursor[2];
-	string_buffer_t prompt_buff;
+	/*
+	  The internal representation of the desired screen contents.
+	*/
+	array_list_t desired;
+	/**
+	  The internal representation of the actual screen contents.
+	*/
+	array_list_t actual;
+	/**
+	   The desired cursor position.
+	 */
+	int desired_cursor[2];
+	/**
+	   The actual cursor position.
+	*/
+	int actual_cursor[2];
+	/**
+	   A stringbuffer containing the prompt which was last printed to
+	   the screen.
+	*/
+	string_buffer_t actual_prompt;
 }
 	screen_t;
 
+/**
+   A struct representing a single line of a screen. Consists of two
+   array_lists, which must always be of the same length.
+*/
 typedef struct
 {
+	/**
+	   The text contents of the line
+	*/
 	array_list_t text;
+	/**
+	   Highlight information for the line
+	*/
 	array_list_t color;
 }
 	line_t;
 
+/**
+   Initialize a new screen struct
+*/
 void s_init( screen_t *s );
+
+/**
+   Free all memory used by the specified screen struct
+*/
 void s_destroy( screen_t *s );
 
+/**
+   This is the main function for the screen putput library. It is used
+   to define the desired contents of the screen. The screen command
+   will use it's knowlege of the current contents of the screen in
+   order to render the desired output using as few terminal commands
+   as possible.
+*/
 void s_write( screen_t *s, 
 			  wchar_t *prompt, 
-			  wchar_t *b,
-			  int *c, 
-			  int cursor );
+			  wchar_t *commandline,
+			  int *colors, 
+			  int cursor_pos );
+
+/** 
+	This function resets the screen buffers internal knowledge about
+	the contents of the screen. Use this function when some other
+	function than s_write has written to the screen.
+*/
 void s_reset( screen_t *s );
 
 #endif