Doxygenate src/document/ (but not subdirs)

src/document/docdata.c

@@ -1,4 +1,5 @@
-/* The document->data tools */
+/** The document->data tools
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"

src/document/document.c

@@ -1,4 +1,5 @@
-/* The document base functionality */
+/** The document base functionality
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"

src/document/document.h

@@ -18,7 +18,7 @@ struct frameset_desc;
 struct module;
 struct screen_char;
 
-/* Nodes are used for marking areas of text on the document canvas as
+/** Nodes are used for marking areas of text on the document canvas as
  * searchable. */
 struct node {
 	LIST_HEAD(struct node);
@@ -27,14 +27,14 @@ struct node {
 };
 
 
-/* The document line consisting of the chars ready to be copied to the terminal
+/** The document line consisting of the chars ready to be copied to
- * screen. */
+ * the terminal screen. */
 struct line {
 	struct screen_char *chars;
 	int length;
 };
 
-/* Codepage status */
+/** Codepage status */
 enum cp_status {
 	CP_STATUS_NONE,
 	CP_STATUS_SERVER,
@@ -83,18 +83,18 @@ struct link {
 	unsigned char *where_img;
 	unsigned char *title;
 
-	/* The set of characters belonging to this link (their coordinates
+	/** The set of characters belonging to this link (their coordinates
-	 * in the document) - each character has own {struct point}. */
+	 * in the document) - each character has own struct point. */
 	struct point *points;
 	int npoints;
 
 	int number;
 
-	/* This is supposed to be the colour-pair of the link, but the actual
+	/** This is supposed to be the colour-pair of the link, but the actual
 	 * colours on the canvas can differ--e.g., with image links. */
 	struct color_pair color;
 
-	/* XXX: They don't neccessary need to be link-specific, but we just
+	/*! XXX: They don't neccessary need to be link-specific, but we just
 	 * don't support them for any other elements for now. Well, we don't
 	 * even have a good place where to store them in that case. */
 	LIST_OF(struct script_event_hook) *event_hooks;
@@ -143,26 +143,26 @@ struct document {
 	LIST_OF(struct node) nodes;
 
 #ifdef CONFIG_ECMASCRIPT
-	/* ECMAScript snippets to be executed during loading the document into
+	/** ECMAScript snippets to be executed during loading the document into
 	 * a window.  This currently involves <script>s and onLoad handlers.
 	 * Note that if you hit a string beginning by '^' here, it is followed
 	 * by an external reference - you must wait with processing other items
 	 * until it gets resolved and loaded. New items are guaranteed to
 	 * always appear at the list end. */
 	LIST_OF(struct string_list_item) onload_snippets;
-	/* FIXME: We should externally maybe using cache_entry store the
+	/** \todo FIXME: We should externally maybe using cache_entry store the
 	 * dependencies between the various entries so nothing gets removed
 	 * unneeded. */
 	struct uri_list ecmascript_imports;
-	/* used by setTimeout */
+	/** used by setTimeout */
 	timer_id_T timeout;
 #endif
 #ifdef CONFIG_CSS
-	/* FIXME: We should externally maybe using cache_entry store the
+	/** \todo FIXME: We should externally maybe using cache_entry store the
 	 * dependencies between the various entries so nothing gets removed
 	 * unneeded. */
 	struct uri_list css_imports;
-	/* Calculated from the id's of all the cache entries in css_imports.
+	/** Calculated from the id's of all the cache entries in #css_imports.
 	 * Used for checking rerendering for available CSS imports. */
 	unsigned long css_magic;
 #endif
@@ -172,15 +172,17 @@ struct document {
 	struct cache_entry *cached;
 
 	struct frame_desc *frame;
-	struct frameset_desc *frame_desc; /* RENAME ME */
+	struct frameset_desc *frame_desc; /**< \todo RENAME ME */
 	struct document_refresh *refresh;
 
 	struct line *data;
 
 	struct link *links;
-	/* Arrays with one item per rendered document's line. */
+	/** @name Arrays with one item per rendered document's line.
-	struct link **lines1; /* The first link on the line. */
+	 * @{ */
-	struct link **lines2; /* The last link on the line. */
+	struct link **lines1; /**< The first link on the line. */
+	struct link **lines2; /**< The last link on the line. */
+	/** @} */
 
 	struct search *search;
 	struct search **slines1;
@@ -190,32 +192,34 @@ struct document {
 	unsigned char buf[7];
 	unsigned char buf_length;
 #endif
-	unsigned int id; /* Used to check cache entries. */
+	unsigned int id; /**< Used to check cache entries. */
 
 	int cp;
-	int width, height; /* size of document */
+	int width, height; /**< size of document */
 	int nlinks;
 	int nsearch;
 	color_T bgcolor;
 
 	enum cp_status cp_status;
-	unsigned int links_sorted:1; /* whether links are already sorted */
+	unsigned int links_sorted:1; /**< whether links are already sorted */
 };
 
 #define document_has_frames(document_) ((document_) && (document_)->frame_desc)
 
-/* Initializes a document and its canvas. */
+/** Initializes a document and its canvas.
-/* Return NULL on allocation failure. */
+ * @returns NULL on allocation failure.
+ * @relates document */
 struct document *
 init_document(struct cache_entry *cached, struct document_options *options);
 
-/* Releases the document and all its resources. */
+/** Releases the document and all its resources.
+ * @relates document */
 void done_document(struct document *document);
 
-/* Free's the allocated members of the link. */
+/** Free's the allocated members of the link. */
 void done_link_members(struct link *link);
 
-/* Calculates css magic from available CSS imports. Used for determining
+/** Calculates css magic from available CSS imports. Used for determining
  * validity of formatted documents in the cache. */
 unsigned long get_document_css_magic(struct document *document);
 
@@ -223,7 +227,8 @@ void update_cached_document_options(void);
 
 struct document *get_cached_document(struct cache_entry *cached, struct document_options *options);
 
-/* Release a reference to the document. */
+/** Release a reference to the document.
+ * @relates document */
 void release_document(struct document *document);
 
 int get_format_cache_size(void);
@@ -234,7 +239,7 @@ void shrink_format_cache(int);
 
 extern struct module document_module;
 
-/* FIXME: support for entities and all Unicode characters.
+/** \todo FIXME: support for entities and all Unicode characters.
  * (Unpaired surrogates should be rejected, so that the ECMAScript
  * interface can convert the access key to UTF-16.)
  * For now, we only support simple printable character.  */

src/document/forms.c

@@ -1,4 +1,5 @@
-/* The document base functionality */
+/** The document base functionality
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"

src/document/forms.h

@@ -18,17 +18,18 @@ enum form_method {
 struct form {
 	LIST_HEAD(struct form);
 
-	/* The value of @form_num serves both as a unique ID of the form.
+	/** The value of @c form_num serves both as a unique ID of the form.
-	 * However @form_num and @form_end also stores information about where
+	 * However @c form_num and #form_end also stores information about where
 	 * in the source the form is positioned. Combined they are used to
 	 * figured which form items belong to which forms after rendering
 	 * tables.
 	 *
-	 * Initially the range between @form_num and @form_end will stretch from
+	 * Initially the range between @c form_num and #form_end will
-	 * 0 to INT_MAX. When a new form is added the range is partitioned so
+	 * stretch from 0 to INT_MAX. When a new form is added the
-	 * the forms each has unique source ranges. */
+	 * range is partitioned so the forms each has unique source
+	 * ranges. */
 	int form_num;
-	int form_end;
+	int form_end;		/**< @see #form_num */
 
 	unsigned char *action;
 	unsigned char *name;
@@ -76,20 +77,20 @@ struct form_control {
 	struct form *form;
 	int g_ctrl_num;
 
-	/* The value of @position is relative to the place of the form item in
+	/** The value of @c position is relative to the place of the
-	 * the source. */
+	 * form item in the source. */
 	int position;
 
 	enum form_type type;
 	enum form_mode mode;
 
-	unsigned char *id; /* used by scripts */
+	unsigned char *id; /**< used by scripts */
 	unsigned char *name;
 	unsigned char *alt;
-	/* For FC_TEXT, FC_PASSWORD, and FC_TEXTAREA: @default_value
+	/** Default value, cannot be changed by document scripts.
-	 * is in the charset of the document.
+	 * - For ::FC_TEXT, ::FC_PASSWORD, and ::FC_TEXTAREA:
-	 *
+	 *   @c default_value is in the charset of the document.
-	 * For FC_FILE: The parser does not set @default_value.  */
+	 * - For ::FC_FILE: The parser does not set @c default_value.  */
 	unsigned char *default_value;
 	int default_state;
 	int size;
@@ -98,11 +99,11 @@ struct form_control {
 	int maxlength;
 	int nvalues;
 	unsigned char **values;
-	/* For FC_SELECT: @labels are in the charset of the terminal.
+	/** Labels in a selection menu.
-	 * (That charset can be UTF-8 only if CONFIG_UTF8 is defined,
+	 * - For ::FC_SELECT: @c labels are in the charset of the terminal.
-	 * and is assumed to be unibyte otherwise.)  The charset of
+	 *   (That charset can be UTF-8 only if CONFIG_UTF8 is defined,
-	 * the document and the UTF-8 I/O option have no effect
+	 *   and is assumed to be unibyte otherwise.)  The charset of
-	 * here.  */
+	 *   the document and the UTF-8 I/O option have no effect here.  */
 	unsigned char **labels;
 	struct menu_item *menu;
 };

src/document/options.c

@@ -1,4 +1,5 @@
-/* Document options/setup workshop */
+/** Document options/setup workshop
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"

src/document/options.h

@@ -7,7 +7,7 @@
 
 struct session;
 
-/* Active link coloring options */
+/** Active link coloring options */
 struct active_link_options {
 	unsigned int color:1;
 	unsigned int underline:1;
@@ -17,14 +17,14 @@ struct active_link_options {
 	color_T bg;
 };
 
-/* This mostly acts as a option cache so rendering will be faster. However it
+/** This mostly acts as a option cache so rendering will be faster. However it
  * is also used to validate and invalidate documents in the format cache as to
  * whether they satisfy the current state of the document options. */
 struct document_options {
 	enum color_mode color_mode;
-	/* cp is the codepage for which the document is being formatted;
+	/** cp is the codepage for which the document is being formatted;
 	 * typically it is the codepage of a terminal.  It is set in
-	 * render_document_frames.  */
+	 * render_document_frames().  */
 	int cp, assume_cp, hard_assume;
 	int margin;
 	int num_links_key;
@@ -32,7 +32,8 @@ struct document_options {
 	int meta_link_display;
 	int default_form_input_size;
 
-	/* The default (fallback) colors. */
+	/** @name The default (fallback) colors.
+	 * @{ */
 	color_T default_fg;
 	color_T default_bg;
 	color_T default_link;
@@ -41,18 +42,22 @@ struct document_options {
 	color_T default_bookmark_link;
 #endif
 	color_T default_image_link;
+	/** @} */
 
-	/* Color model/optimizations */
+	/** Color model/optimizations */
 	enum color_flags color_flags;
 
 	/* XXX: Keep boolean options grouped to save padding */
 #ifdef CONFIG_CSS
-	/* CSS stuff */
+	/** @name CSS stuff
+	 * @{ */
 	unsigned int css_enable:1;
 	unsigned int css_import:1;
+	/** @} */
 #endif
 
-	/* HTML stuff */
+	/** @name HTML stuff
+	 * @{ */
 	unsigned int tables:1;
 	unsigned int table_order:1;
 	unsigned int frames:1;
@@ -63,14 +68,19 @@ struct document_options {
 	unsigned int underline_links:1;
 
 	unsigned int wrap_nbsp:1;
+	/** @} */
 
-	/* Plain rendering stuff */
+	/** @name Plain rendering stuff
+	 * @{ */
 	unsigned int plain_display_links:1;
 	unsigned int plain_compress_empty_lines:1;
+	/** @} */
 
-	/* Link navigation */
+	/** @name Link navigation
+	 * @{ */
 	unsigned int links_numbering:1;
 	unsigned int use_tabindex:1;
+	/** @} */
 
 	unsigned int plain:1;
 	unsigned int wrap:1;
@@ -78,41 +88,44 @@ struct document_options {
 	/* XXX: Everything past this comment is specialy handled by compare_opt() */
 	unsigned char *framename;
 
-	/* The position of the window (box.x and box.y)
+	/** The location of the window in which the document is rendered.
 	 *
-	 *	This is not compared at all since it doesn't make any
+	 * <dl>
+	 * <dt>The position of the window (box.x and box.y)
+	 *
+	 *  <dd>This is not compared at all since it doesn't make any
 	 *	difference what position the document will fit into a frameset
 	 *	or so.
 	 *
-	 * The width of the window (box.width)
+	 * <dt>The width of the window (box.width)
 	 *
-	 *	This controls how wide tables can be rendered and so on. It is
+	 *  <dd>This controls how wide tables can be rendered and so on. It is
 	 *	thus also to blame for the extra memory consumption when
 	 *	resizing because all documents has to be rerendered. We only
-	 *	need to compare it if not @plain.
+	 *	need to compare it if not #plain.
 	 *
-	 * The height of the window (box.height)
+	 * <dt>The height of the window (box.height)
 	 *
-	 *	Only documents containing textarea or frames uses it and we
+	 *  <dd>Only documents containing textarea or frames uses it and we
-	 *	only compare it if @needs_height is set.
+	 *	only compare it if #needs_height is set.
-	 */
+	 * </dl> */
 	struct box box;
 	unsigned int needs_height:1;
 	unsigned int needs_width:1;
 
-	/* Internal flag for rerendering */
+	/** Internal flag for rerendering */
 	unsigned int no_cache:1;
 	unsigned int gradual_rerendering:1;
 
 #ifdef CONFIG_UTF8
 	unsigned int utf8:1;
 #endif /* CONFIG_UTF8 */
-	/* Active link coloring */
+	/** Active link coloring.
-	/* This is mostly here to make use of this option cache so link
+	 * This is mostly here to make use of this option cache so
-	 * drawing is faster. --jonas */
+	 * link drawing is faster. --jonas */
 	struct active_link_options active_link;
 
-	/* Options related with IMG tag */
+	/** Options related with IMG tag */
 	struct {
 		unsigned char *prefix;
 		unsigned char *suffix;
@@ -124,18 +137,22 @@ struct document_options {
 	} image_link;
 };
 
-/* Fills the structure with values from the option system. */
+/** Fills the structure with values from the option system.
+ * @relates document_options */
 void init_document_options(struct document_options *doo);
 
-/* Free allocated document options. */
+/** Free allocated document options.
+ * @relates document_options */
 void done_document_options(struct document_options *options);
 
-/* Copies the values of one struct @from to the other @to.
+/** Copies the values of one struct @a from to the other @a to.
- * Note that the framename is dynamically allocated. */
+ * Note that the document_options.framename is dynamically allocated.
+ * @relates document_options */
 void copy_opt(struct document_options *to, struct document_options *from);
 
 /* Compares comparable values from the two structures according to
- * the comparable members described in the struct definition. */
+ * the comparable members described in the struct definition.
+ * @relates document_options */
 int compare_opt(struct document_options *o1, struct document_options *o2);
 
 #define use_document_fg_colors(o) \
@@ -144,7 +161,7 @@ int compare_opt(struct document_options *o1, struct document_options *o2);
 #define use_document_bg_colors(o) \
 	((o)->color_mode != COLOR_MODE_MONO && (o)->use_document_colors == 2)
 
-/* Increments the numeric value of the option identified by option_name,
+/** Increments the numeric value of the option identified by @a option_name,
  * resetting it to the minimum value when it is already at the maximum value,
  * and redraws the document. */
 void toggle_document_option(struct session *ses, unsigned char *option_name);

src/document/refresh.c

@@ -1,4 +1,5 @@
-/* Document (meta) refresh. */
+/** Document (meta) refresh.
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -59,8 +60,9 @@ done_document_refresh(struct document_refresh *refresh)
 	mem_free(refresh);
 }
 
-/* Timer callback for @refresh->timer.  As explained in @install_timer,
+/** Timer callback for document_refresh.timer.  As explained in
- * this function must erase the expired timer ID from all variables.  */
+ * install_timer(), this function must erase the expired timer ID from
+ * all variables.  */
 static void
 do_document_refresh(void *data)
 {

src/document/renderer.c

@@ -1,4 +1,5 @@
-/* HTML renderer */
+/** HTML renderer
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -40,12 +41,12 @@
 
 
 #ifdef CONFIG_ECMASCRIPT
-/* XXX: This function is de facto obsolete, since we do not need to copy
+/** @todo XXX: This function is de facto obsolete, since we do not need to copy
  * snippets around anymore (we process them in one go after the document is
  * loaded; gradual processing was practically impossible because the snippets
  * could reorder randomly during the loading - consider i.e.
- * <body onLoad><script></body>: first just <body> is loaded, but then the
+ * @<body onLoad>@<script>@</body>: first just @<body> is loaded, but then the
- * rest of the document is loaded and <script> gets before <body>; do not even
+ * rest of the document is loaded and @<script> gets before @<body>; do not even
  * imagine the trouble with rewritten (through scripting hooks) documents;
  * besides, implementing document.write() will be much simpler).
  * But I want to take no risk by reworking that now. --pasky */

src/document/view.h

@@ -19,8 +19,8 @@ struct document_view {
 	struct document *document;
 	struct view_state *vs;
 
-	struct box box;	/* pos and size of window */
+	struct box box;	/**< pos and size of window */
-	int last_x, last_y; /* last pos of window */
+	int last_x, last_y; /**< last pos of window */
 	int depth;
 	int used;
 };