Merge commit 'pasky.or.cz/elinks-0.12' into elinks-0.13

There were conflicts in src/document/css/ because 0.12.GIT switched
to LIST_OF(struct css_selector) and 0.13.GIT switched to struct
css_selector_set.  Resolved by using LIST_OF(struct css_selector)
inside struct css_selector_set.

src/Doxyfile

@@ -0,0 +1,275 @@
+# Doxyfile 1.5.2
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = ELinks
+PROJECT_NUMBER         = 0.13.GIT
+OUTPUT_DIRECTORY       = ../doc/api
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = "The $name class" \
+                         "The $name widget" \
+                         "The $name file" \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = .
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+MULTILINE_CPP_IS_BRIEF = NO
+DETAILS_AT_TOP         = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 3
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = YES
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_DIRECTORIES       = NO
+FILE_VERSION_FILTER    = 
+
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+INPUT                  = .
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c \
+                         *.h \
+                         *.inc
+RECURSIVE              = YES
+EXCLUDE                = 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = 
+EXCLUDE_SYMBOLS        = 
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+SOURCE_BROWSER         = NO
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = NO
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+ALPHABETICAL_INDEX     = NO
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_FOOTER            = 
+HTML_STYLESHEET        = 
+HTML_ALIGN_MEMBERS     = YES
+GENERATE_HTMLHELP      = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NO
+TREEVIEW_WIDTH         = 250
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = NO
+USE_PDFLATEX           = NO
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_SCHEMA             = 
+XML_DTD                = 
+XML_PROGRAMLISTING     = YES
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+GENERATE_AUTOGEN_DEF   = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor   
+#---------------------------------------------------------------------------
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = "LIST_OF(element_T)=element_T list" \
+                         CONFIG_DEBUG \
+                         CONFIG_UTF8 \
+                         HAVE_VARIADIC_MACROS
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references   
+#---------------------------------------------------------------------------
+
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool   
+#---------------------------------------------------------------------------
+
+CLASS_DIAGRAMS         = NO
+MSCGEN_PATH            = 
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = YES
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+DOT_GRAPH_MAX_NODES    = 50
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine   
+#---------------------------------------------------------------------------
+
+SEARCHENGINE           = NO

src/Makefile

@@ -45,7 +45,7 @@ elinks: $(LIB_O_NAME) vernum.o
 TAGS:
 	cd $(srcdir) \
 	&& find . \( -name "*.[ch]" -o -name "*.inc" \) -print \
-	| etags --regex='{c}/INIT_LIST_HEAD(\([[:alnum:]_]+\))/\1/' \
+	| etags --regex='{c}/INIT_LIST_OF([^,]*,[ \t]*\([[:alnum:]_]+\))/\1/' \
 		--regex='{c}/struct_hierbox_browser(\n[ \t]*\([[:alnum:]_]+\),/\1/m' \
 		--regex='{c}/^ACTION_(\([[:alnum:]_]+\),[^,]*,[ \t]*\([[:alnum:]_]+\),/ACT_\1_\2/' \
 		--language=c -

src/bfu/hierbox.h

@@ -21,8 +21,8 @@ struct hierbox_browser {
 	const struct hierbox_browser_button *buttons;
 	size_t buttons_size;
 
-	struct list_head boxes;
+	LIST_OF(struct listbox_data) boxes;
-	struct list_head dialogs;
+	LIST_OF(struct hierbox_dialog_list_item) dialogs;
 	struct listbox_item root;
 	const struct listbox_ops *ops;
 

src/bfu/inpfield.h

@@ -30,7 +30,7 @@ struct widget_info_field {
 struct widget_data_info_field {
 	int vpos;
 	int cpos;
-	struct list_head history;
+	LIST_OF(struct input_history_entry) history;
 	struct input_history_entry *cur_hist;
 };
 

src/bfu/inphist.c

@@ -58,7 +58,8 @@ menu_tab_compl(struct terminal *term, void *item_, void *dlg_data_)
 /* Complete to last unambiguous character, and display menu for all possible
  * further completions. */
 void
-do_tab_compl(struct dialog_data *dlg_data, struct list_head *history)
+do_tab_compl(struct dialog_data *dlg_data,
+	     LIST_OF(struct input_history_entry) *history)
 {
 	struct terminal *term = dlg_data->win->term;
 	struct widget_data *widget_data = selected_widget(dlg_data);
@@ -104,7 +105,8 @@ strcommonlen(unsigned char *a, unsigned char *b)
  * completes `go' to `google.com' and `google.com/' to `google.com/search?q='.
  */
 void
-do_tab_compl_unambiguous(struct dialog_data *dlg_data, struct list_head *history)
+do_tab_compl_unambiguous(struct dialog_data *dlg_data,
+			 LIST_OF(struct input_history_entry) *history)
 {
 	struct string completion;
 	struct widget_data *widget_data = selected_widget(dlg_data);
@@ -188,7 +190,8 @@ tab_complete_file_menu(struct terminal *term, void *path_, void *dlg_data_)
 }
 
 void
-do_tab_compl_file(struct dialog_data *dlg_data, struct list_head *history)
+do_tab_compl_file(struct dialog_data *dlg_data,
+		  LIST_OF(struct input_history_entry) *history)
 {
 	struct widget_data *widget_data = selected_widget(dlg_data);
 

src/bfu/inphist.h

@@ -12,7 +12,7 @@ struct input_history_entry {
 };
 
 struct input_history {
-	struct list_head entries;
+	LIST_OF(struct input_history_entry) entries;
 	int size;
 	unsigned int dirty:1;
 	unsigned int nosave:1;
@@ -42,9 +42,12 @@ struct input_history {
 
 void add_to_input_history(struct input_history *, unsigned char *, int);
 
-void do_tab_compl(struct dialog_data *, struct list_head *);
+void do_tab_compl(struct dialog_data *,
-void do_tab_compl_file(struct dialog_data *, struct list_head *);
+		  LIST_OF(struct input_history_entry) *);
-void do_tab_compl_unambiguous(struct dialog_data *, struct list_head *);
+void do_tab_compl_file(struct dialog_data *,
+		       LIST_OF(struct input_history_entry) *);
+void do_tab_compl_unambiguous(struct dialog_data *,
+			      LIST_OF(struct input_history_entry) *);
 
 /* Load history file from elinks home. */
 int load_input_history(struct input_history *history, unsigned char *filename);

src/bfu/listbox.c

@@ -407,7 +407,7 @@ display_listbox_item(struct listbox_item *item, void *data_, int *offset)
 					str[1] = BORDER_SDLCORNER;
 				}
 			} else {
-				struct list_head *p = data->box->items;
+				LIST_OF(struct listbox_item) *p = data->box->items;
 
 				if (p->next == item) {
 					str[1] = BORDER_SULCORNER;

src/bfu/listbox.h

@@ -105,7 +105,7 @@ struct listbox_data {
 	struct listbox_item *top; /* Item which is on the top line of the box */
 
 	int sel_offset; /* Offset of selected item against the box top */
-	struct list_head *items; /* The list being displayed */
+	LIST_OF(struct listbox_item) *items; /* The list being displayed */
 };
 
 enum listbox_item_type {
@@ -119,7 +119,7 @@ struct listbox_item {
 	LIST_HEAD(struct listbox_item);
 
 	/* The list may be empty for leaf nodes or non-hiearchic listboxes */
-	struct list_head child;
+	LIST_OF(struct listbox_item) child;
 
 	enum listbox_item_type type;
 	int depth;

src/bookmarks/backend/common.c

@@ -74,7 +74,7 @@ bookmarks_read(void)
 }
 
 void
-bookmarks_write(struct list_head *bookmarks_list)
+bookmarks_write(LIST_OF(struct bookmark) *bookmarks_list)
 {
 	int backend_num = get_opt_int("bookmarks.file_format");
 	struct bookmarks_backend *backend = bookmarks_backends[backend_num];

src/bookmarks/backend/common.h

@@ -10,10 +10,10 @@ struct bookmarks_backend {
 	/* Order matters here. --Zas. */
 	unsigned char *(*filename)(int);
 	void (*read)(FILE *);
-	void (*write)(struct secure_save_info *, struct list_head *);
+	void (*write)(struct secure_save_info *, LIST_OF(struct bookmark) *);
 };
 
 void bookmarks_read(void);
-void bookmarks_write(struct list_head *);
+void bookmarks_write(LIST_OF(struct bookmark) *);
 
 #endif

src/bookmarks/backend/default.c

@@ -128,7 +128,7 @@ read_bookmarks_default(FILE *f)
 /* Saves the bookmarks to file */
 static void
 write_bookmarks_default(struct secure_save_info *ssi,
-		        struct list_head *bookmarks_list)
+		        LIST_OF(struct bookmark) *bookmarks_list)
 {
 	int folder_state = get_opt_bool("bookmarks.folder_state");
 	struct bookmark *bm;

src/bookmarks/backend/xbel.c

@@ -58,16 +58,16 @@ static unsigned char * filename_bookmarks_xbel(int writing);
 static int xbeltree_to_bookmarks_list(struct tree_node *root,
 				      struct bookmark *current_parent);
 static void write_bookmarks_list(struct secure_save_info *ssi,
-				 struct list_head *bookmarks_list,
+				 LIST_OF(struct bookmark) *bookmarks_list,
 				 int n, int folder_state);
 static void write_bookmarks_xbel(struct secure_save_info *ssi,
-				 struct list_head *bookmarks_list);
+				 LIST_OF(struct bookmark) *bookmarks_list);
 
 /* Element */
 struct tree_node {
 	unsigned char *name;		/* Name of the element */
 	unsigned char *text;		/* Text inside the element */
-	struct list_head attrs;		/* {struct attributes} */
+	LIST_OF(struct attributes) attrs;
 	struct tree_node *parent;
 	struct tree_node *children;
 
@@ -134,7 +134,7 @@ read_bookmarks_xbel(FILE *f)
 
 static void
 write_bookmarks_xbel(struct secure_save_info *ssi,
-		     struct list_head *bookmarks_list)
+		     LIST_OF(struct bookmarks) *bookmarks_list)
 {
 	int folder_state = get_opt_bool("bookmarks.folder_state");
 	/* We check for readok in filename_bookmarks_xbel(). */
@@ -208,7 +208,7 @@ print_xml_entities(struct secure_save_info *ssi, const unsigned char *str)
 
 static void
 write_bookmarks_list(struct secure_save_info *ssi,
-		     struct list_head *bookmarks_list,
+		     LIST_OF(struct bookmark) *bookmarks_list,
 		     int n, int folder_state)
 {
 	struct bookmark *bm;

src/bookmarks/bookmarks.c

@@ -32,7 +32,7 @@
 #include "util/string.h"
 
 /* The list of bookmarks */
-INIT_LIST_HEAD(bookmarks);
+INIT_LIST_OF(struct bookmark, bookmarks);
 
 /* Set to 1, if bookmarks have changed. */
 static int bookmarks_dirty = 0;
@@ -147,8 +147,8 @@ init_bookmarks(struct module *module)
 
 /* Clears the bookmark list */
 static void
-free_bookmarks(struct list_head *bookmarks_list,
+free_bookmarks(LIST_OF(struct bookmark) *bookmarks_list,
-	       struct list_head *box_items)
+	       LIST_OF(struct listbox_item) *box_items)
 {
 	struct bookmark *bm;
 
@@ -441,7 +441,7 @@ struct bookmark *
 get_bookmark_by_name(struct bookmark *folder, unsigned char *title)
 {
 	struct bookmark *bookmark;
-	struct list_head *lh;
+	LIST_OF(struct bookmark) *lh;
 
 	lh = folder ? &folder->child : &bookmarks;
 

src/bookmarks/bookmarks.h

@@ -20,12 +20,12 @@ struct bookmark {
 	unsigned char *title;   /* title of bookmark */
 	unsigned char *url;     /* Location of bookmarked item */
 
-	struct list_head child;
+	LIST_OF(struct bookmark) child;
 };
 
 /* Bookmark lists */
 
-extern struct list_head bookmarks; /* struct bookmark */
+extern LIST_OF(struct bookmark) bookmarks;
 
 /* The bookmarks module */
 

src/bookmarks/dialogs.c

@@ -344,7 +344,7 @@ enum move_bookmark_flags {
  * _into_ dest or, if insert_as_child is 0, _after_ dest. */
 static enum move_bookmark_flags
 do_move_bookmark(struct bookmark *dest, int insert_as_child,
-		 struct list_head *src, struct listbox_data *box)
+		 LIST_OF(struct bookmark) *src, struct listbox_data *box)
 {
 	static int move_bookmark_event_id = EVENT_NONE;
 	struct bookmark *bm, *next;

src/cache/cache.c

@@ -24,7 +24,7 @@
 #include "util/time.h"
 
 /* The list of cache entries */
-static INIT_LIST_HEAD(cache_entries);
+static INIT_LIST_OF(struct cache_entry, cache_entries);
 
 static unsigned longlong cache_size;
 static int id_counter = 1;

src/cache/cache.h

@@ -29,7 +29,7 @@ struct cache_entry {
 	/* Items in this list are ALLOCATED IN A NON-STANDARD WAY! Thus if you
 	 * are gonna mess with them (you shouldn't), you need to use the
 	 * mmap suite. */
-	struct list_head frag;		/* -> struct fragment */
+	LIST_OF(struct fragment) frag;
 
 	struct uri *uri;		/* Identifier for the cached data */
 	struct uri *proxy_uri;		/* Proxy identifier or same as @uri */

src/config/cmdline.c

@@ -45,7 +45,7 @@ static unsigned char *remote_url;
 
 static enum retval
 parse_options_(int argc, unsigned char *argv[], struct option *opt,
-               struct list_head *url_list)
+               LIST_OF(struct string_list_item) *url_list)
 {
 	while (argc) {
 		argv++, argc--;
@@ -116,7 +116,8 @@ unknown_option:
 }
 
 enum retval
-parse_options(int argc, unsigned char *argv[], struct list_head *url_list)
+parse_options(int argc, unsigned char *argv[],
+	      LIST_OF(struct string_list_item) *url_list)
 {
 	return parse_options_(argc, argv, cmdline_options, url_list);
 }

src/config/cmdline.h

@@ -4,6 +4,7 @@
 #include "main/main.h"
 #include "util/lists.h"
 
-enum retval parse_options(int, unsigned char *[], struct list_head *);
+enum retval parse_options(int, unsigned char *[],
+			  LIST_OF(struct string_list_item) *);
 
 #endif

src/config/dialogs.c

@@ -924,8 +924,6 @@ push_kbdbind_save_button(struct dialog_data *dlg_data,
 }
 
 
-static INIT_LIST_HEAD(keybinding_dialog_list);
-
 static const struct hierbox_browser_button keybinding_buttons[] = {
 	/* [gettext_accelerator_context(.keybinding_buttons)] */
 	{ N_("~Add"),            push_kbdbind_add_button,            0 },

src/config/kbdbind.c

@@ -27,7 +27,7 @@
 
 static struct action_list action_table[KEYMAP_MAX];
 static struct keymap keymap_table[KEYMAP_MAX];
-static struct list_head keymaps[KEYMAP_MAX]; /* struct keybinding */
+static LIST_OF(struct keybinding) keymaps[KEYMAP_MAX];
 
 static void add_default_keybindings(void);
 
@@ -318,12 +318,12 @@ get_keymap_name(enum keymap_id keymap_id)
 }
 
 
-struct key {
+struct named_key {
-	unsigned char *str;
+	const unsigned char *str;
-	int num;
+	term_event_key_T num;
 };
 
-static struct key key_table[] = {
+static const struct named_key key_table[] = {
 	{ "Enter",	KBD_ENTER },
 	{ "Space",	' ' },
 	{ "Backspace",	KBD_BS },
@@ -351,13 +351,13 @@ static struct key key_table[] = {
 	{ "F10",	KBD_F10 },
 	{ "F11",	KBD_F11 },
 	{ "F12",	KBD_F12 },
-	{ NULL, 0 }
+	{ NULL, KBD_UNDEF }
 };
 
 term_event_key_T
 read_key(const unsigned char *key_str)
 {
-	struct key *key;
+	const struct named_key *key;
 
 	if (key_str[0] && !key_str[1])
 		return key_str[0];
@@ -438,8 +438,8 @@ add_keystroke_to_string(struct string *str, struct term_event_keyboard *kbd,
                         int escape)
 {
 	unsigned char key_buffer[3] = "\\x";
-	unsigned char *key_string = NULL;
+	const unsigned char *key_string = NULL;
-	struct key *key;
+	const struct named_key *key;
 
 	if (kbd->key == KBD_UNDEF) return;
 
@@ -459,7 +459,7 @@ add_keystroke_to_string(struct string *str, struct term_event_keyboard *kbd,
 
 	if (!key_string) {
 		key_string = key_buffer + 1;
-		*key_string = (unsigned char) kbd->key;
+		key_buffer[1] = (unsigned char) kbd->key;
 		if (escape && strchr("'\"\\", kbd->key))
 			key_string--;
 	}

src/config/options.c

@@ -52,7 +52,7 @@
  * (struct option *) instead. This applies to bookmarks, global history and
  * listbox items as well, though. --pasky */
 
-static INIT_LIST_HEAD(options_root_tree);
+static INIT_LIST_OF(struct option, options_root_tree);
 
 static struct option options_root = INIT_OPTION(
 	/* name: */	"",
@@ -68,7 +68,7 @@ struct option *config_options;
 struct option *cmdline_options;
 
 static void add_opt_rec(struct option *, unsigned char *, struct option *);
-static void free_options_tree(struct list_head *, int recursive);
+static void free_options_tree(LIST_OF(struct option) *, int recursive);
 
 #ifdef CONFIG_DEBUG
 /* Detect ending '.' (and some others) in options captions.
@@ -305,8 +305,8 @@ get_opt_(
 static void
 add_opt_sort(struct option *tree, struct option *option, int abi)
 {
-	struct list_head *cat = tree->value.tree;
+	LIST_OF(struct option) *cat = tree->value.tree;
-	struct list_head *bcat = &tree->box_item->child;
+	LIST_OF(struct listbox_item) *bcat = &tree->box_item->child;
 	struct option *pos;
 
 	/* The list is empty, just add it there. */
@@ -477,7 +477,7 @@ add_opt(struct option *tree, unsigned char *path, unsigned char *capt,
 				mem_free(option);
 				return NULL;
 			}
-			option->value.tree = (struct list_head *) value;
+			option->value.tree = (LIST_OF(struct option) *) value;
 			break;
 		case OPT_STRING:
 			if (!value) {
@@ -642,10 +642,10 @@ copy_option(struct option *template)
 	return option;
 }
 
-struct list_head *
+LIST_OF(struct option) *
 init_options_tree(void)
 {
-	struct list_head *ptr = mem_alloc(sizeof(*ptr));
+	LIST_OF(struct option) *ptr = mem_alloc(sizeof(*ptr));
 
 	if (ptr) init_list(*ptr);
 	return ptr;
@@ -700,7 +700,7 @@ init_options(void)
 }
 
 static void
-free_options_tree(struct list_head *tree, int recursive)
+free_options_tree(LIST_OF(struct option) *tree, int recursive)
 {
 	while (!list_empty(*tree))
 		delete_option_do(tree->next, recursive);
@@ -730,7 +730,7 @@ register_change_hooks(const struct change_hook_info *change_hooks)
 }
 
 void
-unmark_options_tree(struct list_head *tree)
+unmark_options_tree(LIST_OF(struct option) *tree)
 {
 	struct option *option;
 
@@ -742,7 +742,7 @@ unmark_options_tree(struct list_head *tree)
 }
 
 void
-watermark_deleted_options(struct list_head *tree)
+watermark_deleted_options(LIST_OF(struct option) *tree)
 {
 	struct option *option;
 
@@ -755,7 +755,7 @@ watermark_deleted_options(struct list_head *tree)
 }
 
 static int
-check_nonempty_tree(struct list_head *options)
+check_nonempty_tree(LIST_OF(struct option) *options)
 {
 	struct option *opt;
 
@@ -773,7 +773,8 @@ check_nonempty_tree(struct list_head *options)
 
 void
 smart_config_string(struct string *str, int print_comment, int i18n,
-		    struct list_head *options, unsigned char *path, int depth,
+		    LIST_OF(struct option) *options,
+		    unsigned char *path, int depth,
 		    void (*fn)(struct string *, struct option *,
 			       unsigned char *, int, int, int, int))
 {
@@ -917,7 +918,7 @@ change_hook_ui(struct session *ses, struct option *current, struct option *chang
 /* Bit 2 of show means we should always set visibility, otherwise we set it
  * only on templates. */
 static void
-update_visibility(struct list_head *tree, int show)
+update_visibility(LIST_OF(struct option) *tree, int show)
 {
 	struct option *opt;
 

src/config/options.h

@@ -84,7 +84,7 @@ struct session; /* session/session.h */
 union option_value {
 	/* XXX: Keep first to make @options_root initialization possible. */
 	/* The OPT_TREE list_head is allocated. */
-	struct list_head *tree;
+	LIST_OF(struct option) *tree;
 
 	/* Used by OPT_BOOL, OPT_INT, OPT_CODEPAGE and OPT_LANGUAGE */
 	int number;
@@ -142,7 +142,7 @@ struct option {
 };
 
 #define INIT_OPTION(name, flags, type, min, max, value, desc, capt) \
-	{ NULL_LIST_HEAD, INIT_OBJECT("option"), name, flags, type, min, max, { (struct list_head *) (value) }, desc, capt }
+	{ NULL_LIST_HEAD, INIT_OBJECT("option"), name, flags, type, min, max, { (LIST_OF(struct option) *) (value) }, desc, capt }
 
 extern struct option *config_options;
 extern struct option *cmdline_options;
@@ -160,12 +160,14 @@ struct change_hook_info {
 extern void register_change_hooks(const struct change_hook_info *change_hooks);
 
 
-extern struct list_head *init_options_tree(void);
+extern LIST_OF(struct option) *init_options_tree(void);
-extern void unmark_options_tree(struct list_head *);
+extern void unmark_options_tree(LIST_OF(struct option) *);
-void watermark_deleted_options(struct list_head *);
+void watermark_deleted_options(LIST_OF(struct option) *);
 
-extern void smart_config_string(struct string *, int, int, struct list_head *, unsigned char *, int,
+extern void smart_config_string(struct string *, int, int,
-				void (*)(struct string *, struct option *, unsigned char *, int, int, int, int));
+				LIST_OF(struct option) *, unsigned char *, int,
+				void (*)(struct string *, struct option *,
+					 unsigned char *, int, int, int, int));
 
 extern struct option *copy_option(struct option *);
 extern void delete_option(struct option *);

src/config/opttypes.c

@@ -368,8 +368,8 @@ color_wr(struct option *opt, struct string *str)
 static void
 tree_dup(struct option *opt, struct option *template)
 {
-	struct list_head *new = init_options_tree();
+	LIST_OF(struct option) *new = init_options_tree();
-	struct list_head *tree = template->value.tree;
+	LIST_OF(struct option) *tree = template->value.tree;
 	struct option *option;
 
 	if (!new) return;

src/cookies/cookies.c

@@ -51,7 +51,7 @@
 
 static int cookies_nosave = 0;
 
-static INIT_LIST_HEAD(cookies);
+static INIT_LIST_OF(struct cookie, cookies);
 
 struct c_domain {
 	LIST_HEAD(struct c_domain);
@@ -64,11 +64,10 @@ struct c_domain {
  * struct c_domain.  No other data structures have pointers to these
  * objects.  Currently the domains remain in the list until
  * @done_cookies clears the whole list.  */
-static INIT_LIST_HEAD(c_domains);
+static INIT_LIST_OF(struct c_domain, c_domains);
 
-/* List of servers for which there are cookies.  Each element is a
+/* List of servers for which there are cookies.  */
- * struct cookie_server.  */
+static INIT_LIST_OF(struct cookie_server, cookie_servers);
-static INIT_LIST_HEAD(cookie_servers);
 
 /* Only @set_cookies_dirty may make this nonzero.  */
 static int cookies_dirty = 0;
@@ -908,7 +907,7 @@ init_cookies(struct module *module)
 /* Like @delete_cookie, this function does not set @cookies_dirty.
  * The caller must do that if appropriate.  */
 static void
-free_cookies_list(struct list_head *list)
+free_cookies_list(LIST_OF(struct cookie) *list)
 {
 	while (!list_empty(*list)) {
 		struct cookie *cookie = list->next;

src/cookies/dialogs.c

@@ -25,7 +25,7 @@
 #include "util/string.h"
 
 
-INIT_LIST_HEAD(cookie_queries);
+INIT_LIST_OF(struct cookie, cookie_queries);
 
 static void
 add_cookie_info_to_string(struct string *string, struct cookie *cookie,

src/cookies/dialogs.h

@@ -6,7 +6,7 @@
 #include "terminal/terminal.h"
 #include "util/lists.h"
 
-extern struct list_head cookie_queries;
+extern LIST_OF(struct cookie) cookie_queries;
 
 void accept_cookie_dialog(struct session *ses, void *data);
 extern struct hierbox_browser cookie_browser;

src/dialogs/menu.c

@@ -812,7 +812,7 @@ enum frame_event_status
 pass_uri_to_command(struct session *ses, struct document_view *doc_view,
 		    int which_type)
 {
-	struct list_head *tree = get_opt_tree("document.uri_passing");
+	LIST_OF(struct option) *tree = get_opt_tree("document.uri_passing");
 	enum pass_uri_type type = which_type;
 	struct menu_item *items;
 	struct option *option;
@@ -887,7 +887,7 @@ void
 add_uri_command_to_menu(struct menu_item **mi, enum pass_uri_type type,
 			unsigned char *text)
 {
-	struct list_head *tree = get_opt_tree("document.uri_passing");
+	LIST_OF(struct option) *tree = get_opt_tree("document.uri_passing");
 	struct option *option;
 	int commands = 0;
 	enum menu_item_flags flags = NO_FLAG;

src/document/css/apply.c

@@ -1,4 +1,10 @@
-/* CSS style applier */
+/** CSS style applier
+ * @file
+ *
+ * @todo TODO: A way to disable CSS completely, PLUS a way to stop
+ * various property groups from taking effect. (Ie. way to turn out
+ * effect of 'display: none' or aligning or colors but keeping all the
+ * others.) --pasky */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -28,11 +34,6 @@
 #include "document/html/internal.h"
 
 
-/* TODO: A way to disable CSS completely, PLUS a way to stop various property
- * groups from taking effect. (Ie. way to turn out effect of 'display: none'
- * or aligning or colors but keeping all the others.) --pasky */
-
-
 typedef void (*css_applier_T)(struct html_context *html_context,
 			      struct html_element *element,
 			      struct css_property *prop);
@@ -89,8 +90,9 @@ css_apply_font_attribute(struct html_context *html_context,
 	element->attr.style.attr &= ~prop->value.font_attribute.rem;
 }
 
-/* FIXME: Because the current CSS doesn't provide reasonable defaults for each
+/** @bug FIXME: Because the current CSS doesn't provide reasonable
- * HTML element this applier will cause bad rendering of <pre> tags. */
+ * defaults for each HTML element this applier will cause bad
+ * rendering of @<pre> tags. */
 static void
 css_apply_text_align(struct html_context *html_context,
 		     struct html_element *element, struct css_property *prop)
@@ -99,8 +101,8 @@ css_apply_text_align(struct html_context *html_context,
 	element->parattr.align = prop->value.text_align;
 }
 
-/* XXX: Sort like the css_property_type */
+/*! XXX: Sort like the css_property_type */
-static css_applier_T css_appliers[CSS_PT_LAST] = {
+static const css_applier_T css_appliers[CSS_PT_LAST] = {
 	/* CSS_PT_NONE */		NULL,
 	/* CSS_PT_BACKGROUND */		css_apply_background_color,
 	/* CSS_PT_BACKGROUND_COLOR */	css_apply_background_color,
@@ -113,11 +115,12 @@ static css_applier_T css_appliers[CSS_PT_LAST] = {
 	/* CSS_PT_WHITE_SPACE */	css_apply_font_attribute,
 };
 
-/* This looks for a match in list of selectors. */
+/** This looks for a match in list of selectors. */
 static void
 examine_element(struct html_context *html_context, struct css_selector *base,
 		enum css_selector_type seltype, enum css_selector_relation rel,
-		struct css_selector_set *selectors, struct html_element *element)
+		struct css_selector_set *selectors,
+		struct html_element *element)
 {
 	struct css_selector *selector;
 
@@ -142,7 +145,7 @@ examine_element(struct html_context *html_context, struct css_selector *base,
 		merge_css_selectors(base, sel); \
 		/* Ancestor matches? */ \
 		if (sel->leaves.may_contain_rel_ancestor_or_parent \
-		    && (struct list_head *) element->next \
+		    && (LIST_OF(struct html_element) *) element->next \
 		     != &html_context->stack) { \
 			struct html_element *ancestor; \
 			/* This is less effective than doing reverse iterations,
@@ -152,7 +155,7 @@ examine_element(struct html_context *html_context, struct css_selector *base,
 			 * have to duplicate the whole examine_element(), so if
 			 * profiles won't show it really costs... */ \
 			for (ancestor = element->next; \
-			     (struct list_head *) ancestor \
+			     (LIST_OF(struct html_element) *) ancestor	\
 			      != &html_context->stack;\
 			     ancestor = ancestor->next) \
 				examine_element(html_context, base, \
@@ -221,7 +224,7 @@ struct css_selector *
 get_css_selector_for_element(struct html_context *html_context,
 			     struct html_element *element,
 			     struct css_stylesheet *css,
-			     struct list_head *html_stack)
+			     LIST_OF(struct html_element) *html_stack)
 {
 	unsigned char *code;
 	struct css_selector *selector;
@@ -281,7 +284,7 @@ apply_css_selector_style(struct html_context *html_context,
 
 void
 css_apply(struct html_context *html_context, struct html_element *element,
-	  struct css_stylesheet *css, struct list_head *html_stack)
+	  struct css_stylesheet *css, LIST_OF(struct html_element) *html_stack)
 {
 	struct css_selector *selector;
 

src/document/css/apply.h

@@ -1,3 +1,6 @@
+/*! @file
+ * This is the main entry point for the CSS micro-engine. It throws
+ * all the power of the stylesheets at a given element. */
 
 #ifndef EL__DOCUMENT_CSS_APPLY_H
 #define EL__DOCUMENT_CSS_APPLY_H
@@ -8,28 +11,26 @@ struct css_stylesheet;
 struct html_context;
 struct html_element;
 
-/* This is the main entry point for the CSS micro-engine. It throws all the
+/** Gather all style information for the given @a element, so it can later be
- * power of the stylesheets at a given element. */
+ * applied. Returned value should be freed using done_css_selector().  */
-
-/* Gather all style information for the given @element, so it can later be
- * applied. Returned value should be freed using done_css_selector(). */
 struct css_selector *
 get_css_selector_for_element(struct html_context *html_context,
 			     struct html_element *element,
 			     struct css_stylesheet *css,
-			     struct list_head *html_stack);
+			     LIST_OF(struct html_element) *html_stack);
 
 
-/* Apply properties from an existing selector. */
+/** Apply properties from an existing selector. */
 void
 apply_css_selector_style(struct html_context *html_context,
 			 struct html_element *element,
 			 struct css_selector *selector);
 
-/* This function takes @element and applies its 'style' attribute onto its
+/** This function takes @a element and applies its 'style' attribute onto its
  * attributes (if it contains such an attribute). */
 void
 css_apply(struct html_context *html_context, struct html_element *element,
-	  struct css_stylesheet *css, struct list_head *html_stack);
+	  struct css_stylesheet *css,
+	  LIST_OF(struct html_element) *html_stack);
 
 #endif

src/document/css/css.c

@@ -1,4 +1,5 @@
-/* CSS module management */
+/** CSS module management
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -124,7 +125,8 @@ static int
 change_hook_css(struct session *ses, struct option *current, struct option *changed)
 {
 	if (!strcmp(changed->name, "stylesheet")) {
-		/* TODO: We need to update all entries in format cache. --jonas */
+		/** @todo TODO: We need to update all entries in
+		 * format cache. --jonas */
 		import_default_css();
 	}
 

src/document/css/css.h

@@ -6,20 +6,21 @@ struct css_stylesheet;
 struct module;
 struct uri;
 
-/* TODO: Basicly we need two default stylesheets. One that ELinks controls
+/** @todo TODO: Basicly we need two default stylesheets. One that
- * (which is defined by the defaults of every property, they could however also
+ * ELinks controls (which is defined by the defaults of every
- * be loadable at startup time, e.g. when/if we will have a very generalised
+ * property, they could however also be loadable at startup time,
- * renderer it would be possible to bypass the HTML renderer but would simply
+ * e.g. when/if we will have a very generalised renderer it would be
- * use a HTML stylesheet like the one in CSS2 Appendix A. "A sample style sheet
+ * possible to bypass the HTML renderer but would simply use a HTML
- * for HTML 4.0") and one that the user controls. They should be remerged when
+ * stylesheet like the one in CSS2 Appendix A. "A sample style sheet
- * ever the user reloads the user stylesheet but else they should be pretty
+ * for HTML 4.0") and one that the user controls. They should be
- * static. Together they defines the basic layouting should be done when
+ * remerged when ever the user reloads the user stylesheet but else
- * rendering the document. */
+ * they should be pretty static. Together they defines the basic
+ * layouting should be done when rendering the document. */
 extern struct css_stylesheet default_stylesheet;
 
 extern struct module css_module;
 
-/* This function will try to import the given @url from the cache. */
+/** This function will try to import the given @a url from the cache. */
 void import_css(struct css_stylesheet *css, struct uri *uri);
 
 #endif

src/document/css/parser.c

@@ -1,4 +1,5 @@
-/* CSS main parser */
+/** CSS main parser
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -23,7 +24,8 @@
 
 
 void
-css_parse_properties(struct list_head *props, struct scanner *scanner)
+css_parse_properties(LIST_OF(struct css_property) *props,
+		     struct scanner *scanner)
 {
 	assert(props && scanner);
 
@@ -108,8 +110,11 @@ skip_css_block(struct scanner *scanner)
 	}
 }
 
-/* Atrules grammer:
+/** Parse an atrule from @a scanner and update @a css accordingly.
  *
+ * Atrules grammar:
+ *
+ * @verbatim
  * media_types:
  *	  <empty>
  *	| <ident>
@@ -122,6 +127,7 @@ skip_css_block(struct scanner *scanner)
  *	| '@media' media_types '{' ruleset* '}'
  *	| '@page' <ident>? [':' <ident>]? '{' properties '}'
  *	| '@font-face' '{' properties '}'
+ * @endverbatim
  */
 static void
 css_parse_atrule(struct css_stylesheet *css, struct scanner *scanner,
@@ -184,18 +190,19 @@ struct selector_pkg {
 /** Move a CSS selector and its leaves into a new set.  If a similar
  * selector already exists in the set, merge them.
  *
- * \param sels
+ * @param sels
- *   The set to which \a selector should be moved.  Must not be NULL.
+ *   The set to which @a selector should be moved.  Must not be NULL.
- * \param selector
+ * @param selector
  *   The selector that should be moved.  Must not be NULL.  If it is
  *   already in some set, this function removes it from there.
- * \param watch
+ * @param watch
- *   This function updates \a *watch if it merges that selector into
+ *   This function updates @a *watch if it merges that selector into
- *   another one.  \a watch must not be NULL but \a *watch may be.
+ *   another one.  @a watch must not be NULL but @a *watch may be.
  *
- * \return \a selector or the one into which it was merged.  */
+ * @returns @a selector or the one into which it was merged.  */
 static struct css_selector *
-reparent_selector(struct css_selector_set *sels, struct css_selector *selector,
+reparent_selector(struct css_selector_set *sels,
+                  struct css_selector *selector,
                   struct css_selector **watch)
 {
 	struct css_selector *twin = find_css_selector(sels, selector->type,
@@ -222,16 +229,22 @@ reparent_selector(struct css_selector_set *sels, struct css_selector *selector,
 	return twin ? twin : selector;
 }
 
-/* Our selector grammar:
+/** Parse a comma-separated list of CSS selectors from @a scanner.
+ * Register the selectors in @a css so that get_css_selector_for_element()
+ * will find them, and add them to @a selectors so that the caller can
+ * attach properties to them.
  *
+ * Our selector grammar:
+ *
+ * @verbatim
  * selector:
  *	  element_name? ('#' id)? ('.' class)? (':' pseudo_class)? \
  *		  ((' ' | '>') selector)?
- *
+ * @endverbatim
  */
 static void
 css_parse_selector(struct css_stylesheet *css, struct scanner *scanner,
-		   struct list_head *selectors)
+		   LIST_OF(struct selector_pkg) *selectors)
 {
 	/* Shell for the last selector (the whole selector chain, that is). */
 	struct selector_pkg *pkg = NULL;
@@ -464,16 +477,20 @@ css_parse_selector(struct css_stylesheet *css, struct scanner *scanner,
 }
 
 
-/* Ruleset grammar:
+/** Parse a ruleset from @a scanner to @a css.
  *
+ * Ruleset grammar:
+ *
+ * @verbatim
  * ruleset:
  *	  selector [ ',' selector ]* '{' properties '}'
+ * @endverbatim
  */
 static void
 css_parse_ruleset(struct css_stylesheet *css, struct scanner *scanner)
 {
-	INIT_LIST_HEAD(selectors);
+	INIT_LIST_OF(struct selector_pkg, selectors);
-	INIT_LIST_HEAD(properties);
+	INIT_LIST_OF(struct css_property, properties);
 	struct selector_pkg *pkg;
 
 	css_parse_selector(css, scanner, &selectors);

src/document/css/parser.h

@@ -1,3 +1,6 @@
+/*! @file
+ * This is interface for the value parser. It is intended to be used
+ * only internally inside of the CSS engine. */
 
 #ifndef EL__DOCUMENT_CSS_PARSER_H
 #define EL__DOCUMENT_CSS_PARSER_H
@@ -7,19 +10,17 @@ struct scanner;
 struct css_stylesheet;
 struct uri;
 
-/* This is interface for the value parser. It is intended to be used only
+/** This function takes a semicolon separated list of declarations
- * internally inside of the CSS engine. */
+ * from the given string, parses them to atoms, and chains the newly
-
+ * created struct css_property objects to the specified list.
-/* This function takes a semicolon separated list of declarations from the
+ * @returns positive value in case it recognized a property in the
- * given string, parses them to atoms, and chains the newly created {struct
+ * given string, or zero in case of an error. */
- * css_property}es to the specified list. The function returns positive value
+void css_parse_properties(LIST_OF(struct css_property) *props,
- * in case it recognized a property in the given string, or zero in case of an
+			  struct scanner *scanner);
- * error. */
-void css_parse_properties(struct list_head *props, struct scanner *scanner);
 
 
-/* Parses the @string and adds any recognized selectors + properties to the
+/** Parses the @a string and adds any recognized selectors + properties to the
- * given stylesheet @css. If the selector is already in the stylesheet it
+ * given stylesheet @a css. If the selector is already in the stylesheet it
  * properties are added to the that selector. */
 void css_parse_stylesheet(struct css_stylesheet *css, struct uri *base_uri,
 			  unsigned char *string, unsigned char *end);

src/document/css/property.c

@@ -1,4 +1,5 @@
-/* CSS property info */
+/** CSS property info
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -12,8 +13,8 @@
 #include "document/css/value.h"
 
 
-/* TODO: Use fastfind when we get a lot of properties. */
+/** @todo TODO: Use fastfind when we get a lot of properties.
-/* XXX: But only _WHEN_ we get _A LOT_ of properties, zas! ;-) --pasky */
+ * XXX: But only _WHEN_ we get _A LOT_ of properties, zas! ;-) --pasky */
 struct css_property_info css_property_info[CSS_PT_LAST] = {
 	{ "background",		CSS_PT_BACKGROUND,	 CSS_VT_COLOR,		css_parse_background_value },
 	{ "background-color",	CSS_PT_BACKGROUND_COLOR, CSS_VT_COLOR,		css_parse_color_value },

src/document/css/property.h

@@ -6,16 +6,14 @@
 #include "util/color.h"
 #include "util/lists.h"
 
-/* The {struct css_property} describes one CSS declaration in a rule, therefore
+/** The struct css_property describes one CSS declaration in a rule, therefore
- * being basically a parsed instance of {struct css_property_info}. One list of
+ * being basically a parsed instance of struct css_property_info. One list of
  * these contains all the declarations contained in one rule. */
-
 struct css_property {
 	LIST_HEAD(struct css_property);
 
-	/* Declared property. The enum item name is derived from the property
+	/** Declared property. The enum item name is derived from the
-	 * name, just uppercase it and tr/-/_/. */
+	 * property name, just uppercase it and tr/-/_/. */
-
 	enum css_property_type {
 		CSS_PT_NONE,
 		CSS_PT_BACKGROUND,
@@ -30,9 +28,7 @@ struct css_property {
 		CSS_PT_LAST,
 	} type;
 
-	/* Property value. If it is a pointer, it points always to a memory
+	/** Type of the property value.  Discriminates the #value union.  */
-	 * to be free()d together with this structure. */
-
 	enum css_property_value_type {
 		CSS_VT_NONE,
 		CSS_VT_COLOR,
@@ -41,6 +37,9 @@ struct css_property {
 		CSS_VT_TEXT_ALIGN,
 		CSS_VT_LAST,
 	} value_type;
+
+	/** Property value. If it is a pointer, it points always to a
+	 * memory to be free()d together with this structure. */
 	union css_property_value {
 		void *none;
 		color_T color;
@@ -61,40 +60,40 @@ struct css_property {
 	} value;
 };
 
-/* The {struct css_property_info} describes what values the properties can
- * have and what internal type they have. */
-
 struct css_property_info;
 struct scanner;
 typedef int (*css_property_value_parser_T)(struct css_property_info *propinfo,
 					 union css_property_value *value,
 					 struct scanner *scanner);
 
+/** The struct css_property_info describes what values the properties can
+ * have and what internal type they have. */
 struct css_property_info {
 	unsigned char *name;
 	enum css_property_type type;
 
-	/* This is the storage type, basically describing what to save to
+	/** This is the storage type, basically describing what to save to
 	 * css_property.value. Many properties can share the same valtype.
 	 * The value is basically output of the value parser. */
 	enum css_property_value_type value_type;
 
-	/* This is the property value parser, processing the written form of a
+	/** This is the property value parser, processing the written
-	 * property value. Its job is to take the value string (or scanner's
+	 * form of a property value. Its job is to take the value
-	 * token list in the future) and transform it to a @value form
+	 * string (or scanner's token list in the future) and
-	 * according to the property's @value_type. Although some properties
+	 * transform it to a union css_property_value according to the
-	 * can share a parser, it is expected that most properties will either
+	 * property's #value_type. Although some properties can share
-	 * use a custom one or use a generic parser with property-specific
+	 * a parser, it is expected that most properties will either
-	 * backend specified in @parser_data. */
+	 * use a custom one or use a generic parser with
+	 * property-specific backend specified in #parser_data. */
 	css_property_value_parser_T parser;
 
-	/* In case you use a generic @parser, it can be useful to still give
+	/** In case you use a generic #parser, it can be useful to still give
-	 * it some specific data. You can do so through @parser_data. The
+	 * it some specific data. You can do so through @c parser_data. The
-	 * content is @parser-specific. */
+	 * content is #parser-specific. */
 	void *parser_data;
 };
 
-/* This table contains info about all the known CSS properties. */
+/** This table contains info about all the known CSS properties. */
 extern struct css_property_info css_property_info[];
 
 #endif

src/document/css/scanner.c

@@ -1,4 +1,5 @@
-/* CSS token scanner utilities */
+/** CSS token scanner utilities
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -15,8 +16,7 @@
 #include "util/string.h"
 
 
-/* Bitmap entries for the CSS character groups used in the scanner table */
+/** Bitmap entries for the CSS character groups used in the scanner table */
-
 enum css_char_group {
 	CSS_CHAR_ALPHA		= (1 << 0),
 	CSS_CHAR_DIGIT		= (1 << 1),

src/document/css/scanner.h

@@ -4,88 +4,94 @@
 
 #include "util/scanner.h"
 
-/* The various token types and what they contain. Patterns taken from
+/** The various token types and what they contain. Patterns taken from
- * the flex scanner declarations in the CSS 2 Specification. */
+ * the flex scanner declarations in the CSS 2 Specification.
+ *
+ * Char tokens range from 1 to 255 and have their char value as type
+ * meaning non char tokens have values from 256 and up.
+ *
+ * @verbatim
+ * {...} means char group, <...> means token
+ * {identstart}	[a-z_]|{nonascii}
+ * {ident}	[a-z0-9_-]|{nonascii}
+ * <ident>	{identstart}{ident}*
+ * <name>	{ident}+
+ * <number>	[0-9]+|[0-9]*"."[0-9]+
+ * @endverbatim */
 enum css_token_type {
-	/* Char tokens: */
+	/* Doxygen 1.5.2 does not support member groups inside enum.  */
-
-	/* Char tokens range from 1 to 255 and have their char value as type */
-	/* meaning non char tokens have values from 256 and up. */
 
 	/* Low level string tokens: */
 
-	/* {...} means char group, <...> means token */
+	CSS_TOKEN_IDENT = 256,	/**< @<ident> */
-	/* {identstart}	[a-z_]|{nonascii} */
+	CSS_TOKEN_NUMBER,	/**< @<number> */
-	/* {ident}	[a-z0-9_-]|{nonascii} */
+	/*! Percentage is put because although it looks like being composed
-	/* <ident>	{identstart}{ident}* */
+	 * of @<number> and '@%' floating point numbers are really not
-	/* <name>	{ident}+ */
+	 * allowed but strtol() will round it down for us ;) */
-	/* <number>	[0-9]+|[0-9]*"."[0-9]+ */
+	CSS_TOKEN_PERCENTAGE,	/**< @<number>% */
-
+	CSS_TOKEN_STRING,	/**< Char sequence delimited by matching ' or " */
-	/* Percentage is put because although it looks like being composed of
-	 * <number> and '%' floating point numbers are really not allowed but
-	 * strtol() will round it down for us ;) */
-	CSS_TOKEN_IDENT = 256,	/* <ident> */
-	CSS_TOKEN_NUMBER,	/* <number> */
-	CSS_TOKEN_PERCENTAGE,	/* <number>% */
-	CSS_TOKEN_STRING,	/* Char sequence delimted by matching ' or " */
 
 	/* High level string tokens: */
 
 	/* The various number values; dimension being the most generic */
-	CSS_TOKEN_ANGLE,	/* <number>rad, <number>grad or <number>deg */
+	CSS_TOKEN_ANGLE,	/**< @<number>rad, @<number>grad or @<number>deg */
-	CSS_TOKEN_DIMENSION,	/* <number><ident> */
+	CSS_TOKEN_DIMENSION,	/**< @<number>@<ident> */
-	CSS_TOKEN_EM,		/* <number>em */
+	CSS_TOKEN_EM,		/**< @<number>em */
-	CSS_TOKEN_EX,		/* <number>ex */
+	CSS_TOKEN_EX,		/**< @<number>ex */
-	CSS_TOKEN_FREQUENCY,	/* <number>Hz or <number>kHz */
+	CSS_TOKEN_FREQUENCY,	/**< @<number>Hz or @<number>kHz */
-	CSS_TOKEN_LENGTH,	/* <number>{px,cm,mm,in,pt,pc} */
+	CSS_TOKEN_LENGTH,	/**< @<number>{px,cm,mm,in,pt,pc} */
-	CSS_TOKEN_TIME,		/* <number>ms or <number>s */
+	CSS_TOKEN_TIME,		/**< @<number>ms or @<number>s */
 
-	/* XXX: CSS_TOKEN_HASH conflicts with CSS_TOKEN_HEX_COLOR. Generating
+	/*! XXX: @c CSS_TOKEN_HASH conflicts with #CSS_TOKEN_HEX_COLOR.
-	 * hex color tokens has precedence and the hash token user have to
+	 * Generating hex color tokens has precedence and the hash token
-	 * treat CSS_TOKEN_HASH and CSS_TOKEN_HEX_COLOR alike. */
+	 * user have to treat @c CSS_TOKEN_HASH and #CSS_TOKEN_HEX_COLOR
-	CSS_TOKEN_HASH,		/* #<name> */
+	 * alike. */
-	CSS_TOKEN_HEX_COLOR,	/* #[0-9a-f]\{3,6} */
+	CSS_TOKEN_HASH,		/**< #@<name> */
+	CSS_TOKEN_HEX_COLOR,	/**< #[0-9a-f]@\{3,6} */
 
-	/* For all unknown functions we generate on token contain both function name
+	/*! For all unknown functions we generate on token contain both
-	 * and args so scanning/parsing is easier. Besides we already check for
+	 * function name and args so scanning/parsing is easier. Besides
-	 * ending ')'. */
+	 * we already check for ending ')'.  */
-	/* For known functions where we need several args [like rgb()] we want
+	CSS_TOKEN_FUNCTION,	/**< @<ident>(@<args>) */
-	 * to generate tokens for every arg and arg delimiter ( ',' or ')' ).
+	/*! For known functions where we need several args [like rgb()]
-	 * Because url() is a bit triggy: it can contain both <string> and some
+	 * we want to generate tokens for every arg and arg delimiter
-	 * chars that would other wise make the scanner probably choke we also
+	 * ( ',' or ')' ). */
-	 * include the arg in that token. Besides it will make things like
+	CSS_TOKEN_RGB,		/**< rgb( */
-	 * 'background' property parsing easier. */
+	/*! Because url() is a bit triggy: it can contain both @<string>
-	CSS_TOKEN_FUNCTION,	/* <ident>(<args>) */
+	 * and some chars that would other wise make the scanner probably
-	CSS_TOKEN_RGB,		/* rgb( */
+	 * choke we also include the arg in that token. Besides it will
-	CSS_TOKEN_URL,		/* url(<arg>) */
+	 * make things like 'background' property parsing easier. */
+	CSS_TOKEN_URL,		/**< url(@<arg>) */
 
 	/* @-rule symbols */
-	CSS_TOKEN_AT_KEYWORD,	/* @<ident> */
-	CSS_TOKEN_AT_CHARSET,	/* @charset */
-	CSS_TOKEN_AT_FONT_FACE,	/* @font-face */
-	CSS_TOKEN_AT_IMPORT,	/* @import */
-	CSS_TOKEN_AT_MEDIA,	/* @media */
-	CSS_TOKEN_AT_PAGE,	/* @page */
 
-	CSS_TOKEN_IMPORTANT,	/* !<whitespace>important */
+	CSS_TOKEN_AT_KEYWORD,	/**< @@@<ident> */
+	CSS_TOKEN_AT_CHARSET,	/**< @@charset */
+	CSS_TOKEN_AT_FONT_FACE,	/**< @@font-face */
+	CSS_TOKEN_AT_IMPORT,	/**< @@import */
+	CSS_TOKEN_AT_MEDIA,	/**< @@media */
+	CSS_TOKEN_AT_PAGE,	/**< @@page */
+
+	CSS_TOKEN_IMPORTANT,	/**< !@<whitespace>important */
 
 	/* TODO: Selector stuff: */
-	CSS_TOKEN_SELECT_SPACE_LIST,	/* ~= */
+
-	CSS_TOKEN_SELECT_HYPHEN_LIST,	/* |= */
+	CSS_TOKEN_SELECT_SPACE_LIST,	/**< ~= */
-	CSS_TOKEN_SELECT_BEGIN,		/* ^= */
+	CSS_TOKEN_SELECT_HYPHEN_LIST,	/**< |= */
-	CSS_TOKEN_SELECT_END,		/* $= */
+	CSS_TOKEN_SELECT_BEGIN,		/**< ^= */
-	CSS_TOKEN_SELECT_CONTAINS,	/* *= */
+	CSS_TOKEN_SELECT_END,		/**< $= */
+	CSS_TOKEN_SELECT_CONTAINS,	/**< *= */
 
 	/* Special tokens: */
 
-	/* A special token for unrecognized strings */
+	/** A special token for unrecognized strings */
 	CSS_TOKEN_GARBAGE,
 
-	/* Token type used internally when scanning to signal that the token
+	/** Token type used internally when scanning to signal that the token
 	 * should not be recorded in the scanners token table. */
 	CSS_TOKEN_SKIP,
 
-	/* Another internal token type used both to mark unused tokens in the
+	/** Another internal token type used both to mark unused tokens in the
 	 * scanner table as invalid or when scanning to signal that the
 	 * scanning should end. */
 	CSS_TOKEN_NONE = 0,
@@ -102,7 +108,7 @@ extern struct scanner_info css_scanner_info;
 	 (token_type) == ';' ? (1 <<  8) : \
 	 (token_type) == ')' ? (1 <<  7) : 0)
 
-/* Check whether it is safe to skip the @token when looking for @skipto. */
+/** Check whether it is safe to skip the @a type when looking for @a skipto. */
 static inline int
 check_css_precedence(int type, int skipto)
 {

src/document/css/stylesheet.c

@@ -1,4 +1,5 @@
-/* CSS stylesheet handling */
+/** CSS stylesheet handling
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -25,7 +26,8 @@
 
 
 struct css_selector *
-find_css_selector(struct css_selector_set *sels, enum css_selector_type type,
+find_css_selector(struct css_selector_set *sels,
+                  enum css_selector_type type,
                   enum css_selector_relation rel,
                   const unsigned char *name, int namelen)
 {
@@ -46,8 +48,8 @@ find_css_selector(struct css_selector_set *sels, enum css_selector_type type,
 
 struct css_selector *
 init_css_selector(struct css_selector_set *sels,
-		  enum css_selector_type type,
+                  enum css_selector_type type,
-		  enum css_selector_relation relation,
+                  enum css_selector_relation relation,
                   unsigned char *name, int namelen)
 {
 	struct css_selector *selector;
@@ -92,7 +94,8 @@ set_css_selector_relation(struct css_selector *selector,
 }
 
 struct css_selector *
-get_css_selector(struct css_selector_set *sels, enum css_selector_type type,
+get_css_selector(struct css_selector_set *sels,
+                 enum css_selector_type type,
                  enum css_selector_relation rel,
                  unsigned char *name, int namelen)
 {
@@ -136,7 +139,7 @@ add_selector_property(struct css_selector *selector, struct css_property *prop)
 
 void
 add_selector_properties(struct css_selector *selector,
-                        struct list_head *properties)
+                        LIST_OF(struct css_property) *properties)
 {
 	struct css_property *prop;
 

src/document/css/stylesheet.h

@@ -6,10 +6,12 @@
 
 /* #define DEBUG_CSS */
 
-/* TODO: We need a memory efficient and fast way to define how properties
+/** @file
- * cascade. What we are interested in is making it fast and easy to find
+ * @todo TODO: We need a memory efficient and fast way to define how
- * all properties we need.
+ * properties cascade. What we are interested in is making it fast and
+ * easy to find all properties we need.
  *
+ * @code
  *	struct css_cascade {
  *		struct css_cascade *parent;
  *		struct list_head properties;
@@ -17,6 +19,7 @@
  *			- Can later be turned into a table to not waste memory:
  *			  struct css_property properties[1];
  *	};
+ * @endcode
  *
  * And the selector should then only map a document element into this
  * data structure.
@@ -26,12 +29,13 @@
  * Question is in what direction to apply. It should be possible for the user
  * to overwrite any document provided stylesheet using "!important" so we need
  * to keep track in some table what properties was already applied so we only
- * overwrite when we have to. --jonas */
+ * overwrite when we have to. --jonas
-/* XXX: This is one of the TODOs where I have no clue what is it talking about
+ *
+ * XXX: This is one of the TODOs where I have no clue what is it talking about
  * in particular. Is it obsolete now when we grok 'td.foo p#x>a:hover' without
  * hesitation? --pasky */
 
-/* A set of struct css_selector.  This is currently represented as a
+/** A set of struct css_selector.  This is currently represented as a
  * list but that may be changed later.  Therefore please try not to
  * access the contents directly; instead define new wrapper macros.
  *
@@ -43,30 +47,36 @@
 struct css_selector_set {
 	unsigned char may_contain_rel_ancestor_or_parent;
 
-	/* Keep this away from the beginning of the structure,
+	/** The list of selectors in this set.
+	 *
+	 * Sets are currently represented as lists that
+	 * find_css_selector() then has to search linearly.
+	 * Hashing was also tested but did not help in practice:
+	 * each find_css_selector() call runs approximately one
+	 * strcasecmp(), and a hash function is unlikely to be
+	 * faster than that.  See ELinks bug 789 for details.
+	 *
+	 * Keep this away from the beginning of the structure,
 	 * so that nobody can cast the struct css_selector_set *
-	 * to struct list_head * and get away with it.  */
+	 * to LIST_OF(struct css_selector) * and get away with it.  */
-	struct list_head list;	/* -> struct css_selector */
+	LIST_OF(struct css_selector) list;
 };
 #define INIT_CSS_SELECTOR_SET(set) { 0, { D_LIST_HEAD(set.list) } }
 
-/* The {struct css_selector} is used for mapping elements (or nodes) in the
+/** The struct css_selector is used for mapping elements (or nodes) in the
  * document structure to properties. See README for some hints about how the
  * trees of these span. */
-/* TODO: Hash the selectors at least at the top levels? Binary trees could
- * still give an excellent gain while not giving a constant memory usage hit.
- * --pasky */
 struct css_selector {
 	LIST_HEAD(struct css_selector);
 
-	/* This defines relation between this selector fragment and its
+	/** This defines relation between this selector fragment and its
 	 * parent in the selector tree.
 	 * Update with set_css_selector_relation().  */
 	enum css_selector_relation {
-		CSR_ROOT, /* First class stylesheet member. */
+		CSR_ROOT, /**< First class stylesheet member. */
-		CSR_SPECIFITY, /* Narrowing-down, i.e. the "x" in "foo#x". */
+		CSR_SPECIFITY, /**< Narrowing-down, i.e. the "x" in "foo#x". */
-		CSR_ANCESTOR, /* Ancestor, i.e. the "p" in "p a". */
+		CSR_ANCESTOR, /**< Ancestor, i.e. the "p" in "p a". */
-		CSR_PARENT, /* Direct parent, i.e. the "div" in "div>img". */
+		CSR_PARENT, /**< Direct parent, i.e. the "div" in "div>img". */
 	} relation;
 	struct css_selector_set leaves;
 
@@ -75,11 +85,11 @@ struct css_selector {
 		CST_ID,
 		CST_CLASS,
 		CST_PSEUDO,
-		CST_INVALID, /* Auxiliary for the parser */
+		CST_INVALID, /**< Auxiliary for the parser */
 	} type;
 	unsigned char *name;
 
-	struct list_head properties; /* -> struct css_property */
+	LIST_OF(struct css_property) properties;
 };
 
 
@@ -87,43 +97,43 @@ struct css_stylesheet;
 typedef void (*css_stylesheet_importer_T)(struct css_stylesheet *, struct uri *,
 					unsigned char *url, int urllen);
 
-/* The {struct css_stylesheet} describes all the useful data that was extracted
+/** The struct css_stylesheet describes all the useful data that was extracted
  * from the CSS source. Currently we don't cache anything but the default user
- * stylesheet so it can contain stuff from both <style> tags and @import'ed CSS
+ * stylesheet so it can contain stuff from both @<style> tags and @@import'ed
- * documents. */
+ * CSS documents. */
 struct css_stylesheet {
-	/* The import callback function. */
+	/** The import callback function. */
 	css_stylesheet_importer_T import;
 
-	/* The import callback's data. */
+	/** The import callback's data. */
 	void *import_data;
 
-	/* The set of basic element selectors (which can then somehow
+	/** The set of basic element selectors (which can then somehow
 	 * tree up on inside). */
 	struct css_selector_set selectors;
 
-	/* How deeply nested are we. Limited by MAX_REDIRECTS. */
+	/** How deeply nested are we. Limited by MAX_REDIRECTS. */
 	int import_level;
 };
 
 #define INIT_CSS_STYLESHEET(css, import) \
 	{ import, NULL, INIT_CSS_SELECTOR_SET(css.selectors) }
 
-/* Dynamically allocates a stylesheet. */
+/** Dynamically allocates a stylesheet. */
 struct css_stylesheet *init_css_stylesheet(css_stylesheet_importer_T importer,
                                            void *import_data);
 
-/* Mirror given CSS stylesheet @css1 to an identical copy of itself (including
+/** Mirror given CSS stylesheet @a css1 to an identical copy of itself
- * all the selectors), @css2. */
+ * (including all the selectors), @a css2. */
 void mirror_css_stylesheet(struct css_stylesheet *css1,
 			   struct css_stylesheet *css2);
 
-/* Releases all the content of the stylesheet (but not the stylesheet
+/** Releases all the content of the stylesheet (but not the stylesheet
  * itself). */
 void done_css_stylesheet(struct css_stylesheet *css);
 
 
-/* Returns a new freshly made selector adding it to the given selector
+/** Returns a new freshly made selector adding it to the given selector
  * set, or NULL. */
 struct css_selector *get_css_selector(struct css_selector_set *set,
                                       enum css_selector_type type,
@@ -134,8 +144,8 @@ struct css_selector *get_css_selector(struct css_selector_set *set,
 	get_css_selector((stylesheet) ? &(stylesheet)->selectors : NULL, \
 	                 type, rel, name, namelen)
 
-/* Looks up the selector of the name @name and length @namelen in the
+/** Looks up the selector of the name @a name and length @a namelen in
- * given set of selectors. */
+ * the given set of selectors. */
 struct css_selector *find_css_selector(struct css_selector_set *set,
                                        enum css_selector_type type,
                                        enum css_selector_relation rel,
@@ -144,25 +154,25 @@ struct css_selector *find_css_selector(struct css_selector_set *set,
 #define find_css_base_selector(stylesheet, type, rel, name, namelen) \
 	find_css_selector(&stylesheet->selectors, rel, type, name, namelen)
 
-/* Initialize the selector structure. This is a rather low-level function from
+/** Initialize the selector structure. This is a rather low-level
- * your POV. */
+ * function from your POV. */
 struct css_selector *init_css_selector(struct css_selector_set *set,
                                        enum css_selector_type type,
                                        enum css_selector_relation relation,
                                        unsigned char *name, int namelen);
 
-/* Add all properties from the list to the given @selector. */
+/** Add all properties from the list to the given @a selector. */
 void add_selector_properties(struct css_selector *selector,
-                             struct list_head *properties);
+                             LIST_OF(struct css_property) *properties);
 
-/* Join @sel2 to @sel1, @sel1 taking precedence in all conflicts. */
+/** Join @a sel2 to @a sel1, @a sel1 taking precedence in all conflicts. */
 void merge_css_selectors(struct css_selector *sel1, struct css_selector *sel2);
 
-/* Use this function instead of modifying css_selector.relation directly.  */
+/** Use this function instead of modifying css_selector.relation directly.  */
 void set_css_selector_relation(struct css_selector *,
 			       enum css_selector_relation);
 
-/* Destroy a selector. done_css_stylesheet() normally does that for you. */
+/** Destroy a selector. done_css_stylesheet() normally does that for you. */
 void done_css_selector(struct css_selector *selector);
 
 void init_css_selector_set(struct css_selector_set *set);
@@ -175,7 +185,7 @@ void del_css_selector_from_set(struct css_selector *);
 #define foreach_css_selector(selector, set) foreach (selector, (set)->list)
 
 #ifdef DEBUG_CSS
-/* Dumps the selector tree to stderr. */
+/** Dumps the selector tree to stderr. */
 void dump_css_selector_tree(struct css_selector_set *set);
 #endif
 

src/document/css/value.c

@@ -1,4 +1,5 @@
-/* CSS property value parser */
+/** CSS property value parser
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"

src/document/css/value.h

@@ -1,3 +1,6 @@
+/*! @file
+ * This is interface for the value parser. It is intended to be used
+ * only internally inside of the CSS engine. */
 
 #ifndef EL__DOCUMENT_CSS_VALUE_H
 #define EL__DOCUMENT_CSS_VALUE_H
@@ -5,13 +8,13 @@
 #include "document/css/property.h"
 #include "document/css/scanner.h"
 
-/* This is interface for the value parser. It is intended to be used only
- * internally inside of the CSS engine. */
 
-/* This function takes a value of a specified type from the given scanner and
+/** This function takes a value of a specified type from the given
- * converts it to a reasonable {struct css_property}-ready form. */
+ * scanner and converts it to a reasonable struct css_property-ready
-/* It returns positive integer upon success, zero upon parse error, and moves
+ * form.
- * the string pointer to the byte after the value end. */
+ *
+ * It returns positive integer upon success, zero upon parse error,
+ * and moves the string pointer to the byte after the value end. */
 int css_parse_value(struct css_property_info *propinfo,
 		    union css_property_value *value,
 		    struct scanner *scanner);
@@ -19,42 +22,42 @@ int css_parse_value(struct css_property_info *propinfo,
 
 /* Here come the css_property_value_parsers provided. */
 
-/* Takes no parser_data. */
+/*! Takes no parser_data. */
 int css_parse_background_value(struct css_property_info *propinfo,
 				union css_property_value *value,
 				struct scanner *scanner);
 
-/* Takes no parser_data. */
+/*! Takes no parser_data. */
 int css_parse_color_value(struct css_property_info *propinfo,
 			  union css_property_value *value,
 			  struct scanner *scanner);
 
-/* Takes no parser_data. */
+/*! Takes no parser_data. */
 int css_parse_display_value(struct css_property_info *propinfo,
 			    union css_property_value *value,
 			    struct scanner *scanner);
 
-/* Takes no parser_data. */
+/*! Takes no parser_data. */
 int css_parse_text_decoration_value(struct css_property_info *propinfo,
 				union css_property_value *value,
 				struct scanner *scanner);
 
-/* Takes no parser_data. */
+/*! Takes no parser_data. */
 int css_parse_font_style_value(struct css_property_info *propinfo,
 				union css_property_value *value,
 				struct scanner *scanner);
 
-/* Takes no parser_data. */
+/*! Takes no parser_data. */
 int css_parse_font_weight_value(struct css_property_info *propinfo,
 				union css_property_value *value,
 				struct scanner *scanner);
 
-/* Takes no parser_data. */
+/*! Takes no parser_data. */
 int css_parse_text_align_value(struct css_property_info *propinfo,
 				union css_property_value *value,
 				struct scanner *scanner);
 
-/* Takes no parser_data. */
+/*! Takes no parser_data. */
 int css_parse_white_space_value(struct css_property_info *propinfo,
 				union css_property_value *value,
 				struct scanner *scanner);

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"
@@ -33,7 +34,7 @@
 #include "viewer/text/link.h"
 
 
-static INIT_LIST_HEAD(format_cache);
+static INIT_LIST_OF(struct document, format_cache);
 
 struct document *
 init_document(struct cache_entry *cached, struct document_options *options)

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,21 +83,21 @@ 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. */
-	struct list_head *event_hooks; /* -> struct script_event_hook */
+	LIST_OF(struct script_event_hook) *event_hooks;
 
 	union {
 		unsigned char *name;
@@ -138,31 +138,31 @@ struct document {
 
 	struct document_options options;
 
-	struct list_head forms; /* -> struct form */
+	LIST_OF(struct form) forms;
-	struct list_head tags; /* -> struct tag */
+	LIST_OF(struct tag) tags;
-	struct list_head nodes; /* -> struct node */
+	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. */
-	struct list_head onload_snippets; /* -> struct string_list_item */
+	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;
@@ -36,7 +37,7 @@ struct form {
 	unsigned char *target;
 	enum form_method method;
 
-	struct list_head items; /* -> struct form_control */
+	LIST_OF(struct form_control) items;
 };
 
 
@@ -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/html/internal.h

@@ -59,7 +59,7 @@ struct html_context {
 	 * html/parser/parse.c
 	 * html/parser/stack.c
 	 * html/parser.c */
-	struct list_head stack;
+	LIST_OF(struct html_element) stack;
 
 	/* For parser/parse.c: */
 	unsigned char *eoff; /* For parser/forms.c too */

src/document/html/renderer.c

@@ -1863,7 +1863,7 @@ void
 check_html_form_hierarchy(struct part *part)
 {
 	struct document *document = part->document;
-	INIT_LIST_HEAD(form_controls);
+	INIT_LIST_OF(struct form_control, form_controls);
 	struct form *form;
 	struct form_control *fc, *next;
 

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,18 +41,19 @@
 
 
 #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 */
 static void
 add_snippets(struct ecmascript_interpreter *interpreter,
-             struct list_head *doc_snippets, struct list_head *queued_snippets)
+             LIST_OF(struct string_list_item) *doc_snippets,
+             LIST_OF(struct string_list_item) *queued_snippets)
 {
 	struct string_list_item *doc_current = doc_snippets->next;
 
@@ -110,7 +112,8 @@ add_snippets(struct ecmascript_interpreter *interpreter,
 
 static void
 process_snippets(struct ecmascript_interpreter *interpreter,
-                 struct list_head *snippets, struct string_list_item **current)
+                 LIST_OF(struct string_list_item) *snippets,
+                 struct string_list_item **current)
 {
 	if (!*current)
 		*current = snippets->next;

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;
 };

src/dom/Doxyfile

@@ -188,12 +188,12 @@ PERLMOD_MAKEVAR_PREFIX =
 # Configuration options related to the preprocessor   
 #---------------------------------------------------------------------------
 ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           = 
 INCLUDE_FILE_PATTERNS  = 
-PREDEFINED             = 
+PREDEFINED             = LIST_OF(element_T)="element_T list"
 EXPAND_AS_DEFINED      = 
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------

src/dom/stack.h

@@ -67,8 +67,8 @@ struct dom_stack_state {
 	 * The depth of the state in the stack. This is amongst other things
 	 * used to get the state object data. */
 	unsigned int depth;
-	/** Whether this stack state can be popped with #pop_dom_node,
+	/** Whether this stack state can be popped with pop_dom_node(),
-	 * #pop_dom_nodes, or #pop_dom_state. */
+	 * pop_dom_nodes(), or pop_dom_state(). */
 	unsigned int immutable:1;
 };
 
@@ -112,7 +112,7 @@ enum dom_stack_flag {
 	/** No flag needed. */
 	DOM_STACK_FLAG_NONE = 0,
 
-	/** Free nodes when popping by calling #done_dom_node. */
+	/** Free nodes when popping by calling done_dom_node(). */
 	DOM_STACK_FLAG_FREE_NODES = 1,
 };
 

src/ecmascript/ecmascript.h

@@ -39,7 +39,7 @@ struct ecmascript_interpreter {
 	 * any new snippets in document.onload_snippets). Instead, as we
 	 * go through the list we maintain a pointer to the last processed
 	 * entry. */
-	struct list_head onload_snippets; /* -> struct string_list_item */
+	LIST_OF(struct string_list_item) onload_snippets;
 	struct string_list_item *current_onload_snippet;
 
 	/* ID of the {struct document} where those onload_snippets belong to.

src/formhist/formhist.c

@@ -42,7 +42,7 @@ static struct option_info forms_history_options[] = {
 	NULL_OPTION_INFO,
 };
 
-INIT_LIST_HEAD(saved_forms);
+INIT_LIST_OF(struct formhist_data, saved_forms);
 
 static struct formhist_data *
 new_formhist_item(unsigned char *url)
@@ -386,7 +386,7 @@ get_form_history_value(unsigned char *url, unsigned char *name)
 }
 
 void
-memorize_form(struct session *ses, struct list_head *submit,
+memorize_form(struct session *ses, LIST_OF(struct submitted_value) *submit,
 	      struct form *forminfo)
 {
 	/* [gettext_accelerator_context(memorize_form)] */

src/formhist/formhist.h

@@ -11,7 +11,7 @@ struct formhist_data {
 	OBJECT_HEAD(struct formhist_data);
 
 	/* List of submitted_values for this form */
-	struct list_head *submit;
+	LIST_OF(struct submitted_value) *submit;
 
 	struct listbox_item *box_item;
 
@@ -26,7 +26,9 @@ struct formhist_data {
  * value if present, NULL upon an error. */
 unsigned char *get_form_history_value(unsigned char *url, unsigned char *name);
 
-void memorize_form(struct session *ses, struct list_head *submit, struct form *forminfo);
+void memorize_form(struct session *ses,
+		   LIST_OF(struct submitted_value) *submit,
+		   struct form *forminfo);
 
 int save_formhist_to_file(void);
 void delete_formhist_item(struct formhist_data *form);

src/globhist/globhist.c

@@ -39,7 +39,7 @@
 
 
 INIT_INPUT_HISTORY(global_history);
-INIT_LIST_HEAD(global_history_reap_list);
+INIT_LIST_OF(struct global_history_item, global_history_reap_list);
 
 
 /* GUI stuff. Declared here because done_global_history() frees it. */

src/main/main.c

@@ -62,7 +62,7 @@ static int init_b = 0;
 
 /* Check if either stdin or stdout are pipes */
 static void
-check_stdio(struct list_head *url_list)
+check_stdio(LIST_OF(struct string_list_item) *url_list)
 {
 	assert(!remote_session_flags);
 
@@ -105,7 +105,7 @@ check_cwd(void)
 static void
 init(void)
 {
-	INIT_LIST_HEAD(url_list);
+	INIT_LIST_OF(struct string_list_item, url_list);
 	int fd = -1;
 	enum retval ret;
 

src/main/select.c

@@ -82,7 +82,7 @@ struct bottom_half {
 	void *data;
 };
 
-static INIT_LIST_HEAD(bottom_halves);
+static INIT_LIST_OF(struct bottom_half, bottom_halves);
 
 int
 register_bottom_half_do(select_handler_T fn, void *data)

src/main/timer.c

@@ -24,7 +24,7 @@ struct timer {
 
 /* @timers.next points to the timer with the smallest interval,
  * @timers.next->next to the second smallest, and so on.  */
-static INIT_LIST_HEAD(timers);
+static INIT_LIST_OF(struct timer, timers);
 
 int
 get_timers_count(void)

src/mime/backend/mailcap.c

@@ -42,7 +42,7 @@
 
 struct mailcap_hash_item {
 	/* The entries associated with the type */
-	struct list_head entries; /* -> struct mailcap_entry */
+	LIST_OF(struct mailcap_entry) entries;
 
 	/* The content type of all @entries. Must be last! */
 	unsigned char type[1];
@@ -683,7 +683,7 @@ int default_mime_backend,
     install_signal_handler,
     mimetypes_mime_backend,
     program;
-struct list_head terminals;
+LIST_OF(struct terminal) terminals;
 
 void die(const char *msg, ...)
 {

src/mime/dialogs.c

@@ -146,7 +146,7 @@ void
 menu_list_ext(struct terminal *term, void *fn_, void *xxx)
 {
 	menu_func_T fn = fn_;
-	struct list_head *opt_tree = get_opt_tree("mime.extension");
+	LIST_OF(struct option) *opt_tree = get_opt_tree("mime.extension");
 	struct option *opt;
 	struct menu_item *mi = NULL;
 

src/network/connection.c

@@ -59,9 +59,9 @@ static unsigned int connection_id = 0;
 static int active_connections = 0;
 static timer_id_T keepalive_timeout = TIMER_ID_UNDEF;
 
-static INIT_LIST_HEAD(connection_queue);
+static INIT_LIST_OF(struct connection, connection_queue);
-static INIT_LIST_HEAD(host_connections);
+static INIT_LIST_OF(struct host_connection, host_connections);
-static INIT_LIST_HEAD(keepalive_connections);
+static INIT_LIST_OF(struct keepalive_connection, keepalive_connections);
 
 /* Prototypes */
 static void notify_connection_callbacks(struct connection *conn);

src/network/connection.h

@@ -16,7 +16,7 @@ struct uri;
 struct connection {
 	LIST_HEAD(struct connection);
 
-	struct list_head downloads;
+	LIST_OF(struct download) downloads;
 	struct progress *progress;
 
 	/* If no proxy is used uri and proxied_uri are the same. */
@@ -82,7 +82,7 @@ struct popen_data {
 	unsigned char *filename;
 };
 
-extern struct list_head copiousoutput_data;
+extern LIST_OF(struct popen_data) copiousoutput_data;
 
 int register_check_queue(void);
 

src/network/dns.c

@@ -76,7 +76,7 @@ struct dnsquery {
 static struct dnsquery *dns_queue = NULL;
 #endif
 
-static INIT_LIST_HEAD(dns_cache);
+static INIT_LIST_OF(struct dnsentry, dns_cache);
 
 static void done_dns_lookup(struct dnsquery *query, enum dns_result res);
 

src/network/state.c

@@ -136,7 +136,7 @@ struct strerror_val {
 	unsigned char msg[1]; /* must be last */
 };
 
-static INIT_LIST_HEAD(strerror_buf); /* struct strerror_val */
+static INIT_LIST_OF(struct strerror_val, strerror_buf);
 
 /* It returns convenient error message, depending on @state.
  * It never returns NULL (if one changes that, be warn that

src/osdep/beos/beos.c

@@ -61,7 +61,7 @@ struct active_thread {
 	void *data;
 };
 
-INIT_LIST_HEAD(active_threads);
+INIT_LIST_OF(struct active_thread, active_threads);
 
 int32
 started_thr(void *data)
@@ -114,12 +114,14 @@ rel:
 void
 terminate_osdep(void)
 {
-	struct list_head *p;
+	LIST_OF(struct active_thread) *p;
 	struct active_thread *thrd;
 
 	if (acquire_sem(thr_sem) < B_NO_ERROR) return;
 	foreach (thrd, active_threads) kill_thread(thrd->tid);
 
+	/* Cannot use free_list(active_threads) because it would call
+	 * mem_free(p) and we need free(p).  */
 	while ((p = active_threads.next) != &active_threads) {
 		del_from_list(p);
 		free(p);

src/osdep/os2/os2.c

@@ -436,9 +436,9 @@ resize_window(int x, int y, int old_width, int old_height)
 #if 0
 	unsigned char cmdline[16];
 	sprintf(cmdline, "mode ");
-	snprint(cmdline + 5, 5, x);
+	ulongcat(cmdline + 5, NULL, x, 5, 0);
 	strcat(cmdline, ",");
-	snprint(cmdline + strlen(cmdline), 5, y);
+	ulongcat(cmdline + strlen(cmdline), NULL, y, 5, 0);
 #endif
 	return 0;
 }

src/protocol/auth/auth.c

@@ -26,7 +26,7 @@
 #define DEBUG_HTTP_AUTH
 #endif
 
-static INIT_LIST_HEAD(auth_entry_list);
+static INIT_LIST_OF(struct auth_entry, auth_entry_list);
 
 
 /* Find if url/realm is in auth list. If a matching url is found, but realm is

src/protocol/bittorrent/bittorrent.c

@@ -228,7 +228,7 @@ get_bittorrent_peerwire_max_request_length(void)
 
 
 /* File selection store. */
-static INIT_LIST_HEAD(bittorrent_selections);
+static INIT_LIST_OF(struct bittorrent_selection_info, bittorrent_selections);
 
 struct bittorrent_selection_info {
 	LIST_HEAD(struct bittorrent_selection_info);
@@ -291,7 +291,7 @@ add_bittorrent_selection(struct uri *uri, int *selection, size_t size)
 
 
 /* Message queue. */
-static INIT_LIST_HEAD(bittorrent_messages);
+static INIT_LIST_OF(struct bittorrent_message, bittorrent_messages);
 
 void
 add_bittorrent_message(struct uri *uri, enum connection_state state,

src/protocol/bittorrent/common.c

@@ -465,7 +465,7 @@ struct bittorrent_blacklist_item {
 	bittorrent_id_T id;
 };
 
-static INIT_LIST_HEAD(bittorrent_blacklist);
+static INIT_LIST_OF(struct bittorrent_blacklist_item, bittorrent_blacklist);
 
 
 static struct bittorrent_blacklist_item *

src/protocol/bittorrent/common.h

@@ -117,7 +117,7 @@ struct bittorrent_peer_request {
 
 struct bittorrent_peer_status {
 	/* FIFO-like recording of requests. */
-	struct list_head requests; /* -> struct bittorrent_peer_request */
+	LIST_OF(struct bittorrent_peer_request) requests;
 
 	/* Flags for scheduling updating of the peer state. */
 	unsigned int choked:1;		/* The peer was choked. */
@@ -170,7 +170,7 @@ struct bittorrent_peer_connection {
 
 	/* Outgoing message queue. Note piece messages are maintained entirely
 	 * in the request list in the bittorrent_peer_status struct. */
-	struct list_head queue; /* -> struct bittorrent_peer_request */
+	LIST_OF(struct bittorrent_peer_request) queue;
 
 	/* A bitfield of the available pieces from the peer. */
 	/* The size depends on the number of pieces. */
@@ -270,7 +270,7 @@ struct bittorrent_meta {
 
 	/* A list with information about files in the torrent. */
 	/* The list is a singleton for single-file torrents. */
-	struct list_head files;	/* -> struct bittorrent_file */
+	LIST_OF(struct bittorrent_file) files;
 };
 
 enum bittorrent_connection_mode {
@@ -304,11 +304,11 @@ struct bittorrent_connection {
 	/* Active peer list */
 	/* The size is controlled by the protocol.bittorrent.max_active_peers
 	 * option. */
-	struct list_head peers; 	/* -> struct bittorrent_peer_connection */
+	LIST_OF(struct bittorrent_peer_connection) peers;
 
 	/* List of information about potential peers. */
 	/* TODO: Use hash. */
-	struct list_head peer_pool;	/* -> struct bittorrent_peer */
+	LIST_OF(struct bittorrent_peer) peer_pool;
 
 	/* The peer ID of the client. */
 	bittorrent_id_T peer_id;

src/protocol/bittorrent/dialogs.c

@@ -26,7 +26,7 @@
 
 
 struct bittorrent_download_info {
-	struct list_head labels;	/* -> struct string_list_item */
+	LIST_OF(struct string_list_item) labels;
 	unsigned char *name;
 	int *selection;
 	size_t size;

src/protocol/bittorrent/peerconnect.c

@@ -43,12 +43,12 @@
 static int bittorrent_socket = -1;
 
 /* The active BitTorrent connections sharing the above listening port. */
-static INIT_LIST_HEAD(bittorrent_connections);
+static INIT_LIST_OF(struct bittorrent_connection, bittorrent_connections);
 
 /* The incoming (and pending anonymous) peer connections which has not yet been
  * assigned to a BitTorrent connection because the info hash has not been read
  * from the handshake.  */
-static INIT_LIST_HEAD(bittorrent_peer_connections);
+static INIT_LIST_OF(struct bittorrent_peer_connection, bittorrent_peer_connections);
 
 
 /* Loop the bittorrent connection list and return matching connection

src/protocol/bittorrent/piececache.c

@@ -341,7 +341,7 @@ add_piece_to_bittorrent_free_list(struct bittorrent_piece_cache *cache,
 {
 	struct bittorrent_peer_request *request, *next;
 	uint32_t request_length, piece_length, piece_offset;
-	INIT_LIST_HEAD(requests);
+	INIT_LIST_OF(struct bittorrent_peer_request, requests);
 	uint16_t blocks = 0;
 
 	assert(piece <= bittorrent->meta.pieces);

src/protocol/bittorrent/piececache.h

@@ -60,7 +60,7 @@ struct bittorrent_piece_cache {
 	/* A list of completed and saved entries which has been loaded into
 	 * memory. The allocated memory for all these entries is disposable. The
 	 * entries are sorted in a LRU-manner. */
-	struct list_head queue;	/* -> struct bittorrent_piece_cache_entry */
+	LIST_OF(struct bittorrent_piece_cache_entry) queue;
 
 	/* Remaining pieces are tracked using the remaining_blocks member of the
 	 * piece cache entry and a free list of piece blocks to be requested.
@@ -84,7 +84,7 @@ struct bittorrent_piece_cache {
 	 * cloned flag. The flag is set when piece block requests are cloned. If
 	 * the cloned flag is set when receiving a block then the peer-list is
 	 * searched and requests for the same piece is canceled. */
-	struct list_head free_list;	/* -> struct bittorrent_piece_request */
+	LIST_OF(struct bittorrent_piece_request) free_list;
 	struct bittorrent_piece_cache_entry entries[1];
 };
 

src/protocol/http/blacklist.c

@@ -22,7 +22,7 @@ struct blacklist_entry {
 	unsigned char host[1]; /* Must be last. */
 };
 
-static INIT_LIST_HEAD(blacklist);
+static INIT_LIST_OF(struct blacklist_entry, blacklist);
 
 
 static struct blacklist_entry *

src/protocol/http/http_negotiate.c

@@ -44,7 +44,7 @@ struct negotiate {
 	gss_buffer_desc input_token;
 };
 
-static INIT_LIST_HEAD(negotiate_list);
+static INIT_LIST_OF(struct negotiate, negotiate_list);
 
 static struct negotiate *
 http_negotiate_get(struct uri *uri, int *isnew, int alloc)

src/protocol/test/.gitignore

@@ -0,0 +1 @@
+test_uri

src/session/download.c

@@ -1,4 +1,5 @@
-/* Downloads managment */
+/** Downloads managment
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -62,9 +63,9 @@
 /* TODO: tp_*() should be in separate file, I guess? --pasky */
 
 
-INIT_LIST_HEAD(downloads);
+INIT_LIST_OF(struct file_download, downloads);
 
-INIT_LIST_HEAD(copiousoutput_data);
+INIT_LIST_OF(struct popen_data, copiousoutput_data);
 
 int
 download_is_progressing(struct download *download)
@@ -1032,7 +1033,7 @@ tp_save(struct type_query *type_query)
 	query_file(type_query->ses, type_query->uri, type_query, continue_download, tp_cancel, 1);
 }
 
-/* This button handler uses the add_dlg_button() interface so that pressing
+/** This button handler uses the add_dlg_button() interface so that pressing
  * 'Show header' will not close the type query dialog. */
 static widget_handler_status_T
 tp_show_header(struct dialog_data *dlg_data, struct widget_data *widget_data)
@@ -1045,9 +1046,10 @@ tp_show_header(struct dialog_data *dlg_data, struct widget_data *widget_data)
 }
 
 
-/* FIXME: We need to modify this function to take frame data instead, as we
+/** @bug FIXME: We need to modify this function to take frame data
- * want to use this function for frames as well (now, when frame has content
+ * instead, as we want to use this function for frames as well (now,
- * type text/plain, it is ignored and displayed as HTML). */
+ * when frame has content type text/plain, it is ignored and displayed
+ * as HTML). */
 void
 tp_display(struct type_query *type_query)
 {
@@ -1197,10 +1199,7 @@ do_type_query(struct type_query *type_query, unsigned char *ct, struct mime_hand
 		}
 
 		if (handler && handler->program) {
-			int programlen = strlen(handler->program);
+			safe_strncpy(field, handler->program, MAX_STR_LEN);
-
-			programlen = int_min(programlen, MAX_STR_LEN);
-			memcpy(field, handler->program, programlen);
 		}
 
 		/* xgettext:no-c-format */

src/session/download.h

@@ -27,7 +27,7 @@ struct download {
 
 	struct connection *conn;
 	struct cache_entry *cached;
-	/* The callback is called when connection gets into a progress state,
+	/** The callback is called when connection gets into a progress state,
 	 * after it's over (in a result state), and also periodically after
 	 * the download starts receiving some data. */
 	download_callback_T *callback;
@@ -67,25 +67,25 @@ struct file_download {
 	int notify;
 	struct download download;
 
-	/* Should the file be deleted when destroying the structure */
+	/** Should the file be deleted when destroying the structure */
 	unsigned int delete:1;
 
-	/* Should the download be stopped/interrupted when destroying the structure */
+	/** Should the download be stopped/interrupted when destroying the structure */
 	unsigned int stop:1;
 
-	/* Whether to block the terminal when running the external handler. */
+	/** Whether to block the terminal when running the external handler. */
 	unsigned int block:1;
 
-	/* Whether copiousoutput mode is used by the mailcap entry */
+	/** Whether copiousoutput mode is used by the mailcap entry */
 	unsigned int copiousoutput:1;
 
-	/* The current dialog for this download. Can be NULL. */
+	/** The current dialog for this download. Can be NULL. */
 	struct dialog_data *dlg_data;
 	struct listbox_item *box_item;
 };
 
-/* Stack of all running downloads */
+/** Stack of all running downloads */
-extern struct list_head downloads;
+extern LIST_OF(struct file_download) downloads;
 
 static inline int
 is_in_downloads_list(struct file_download *file_download)

src/session/history.c

@@ -1,4 +1,5 @@
-/* Visited URL history managment - NOT goto_url_dialog history! */
+/** Visited URL history managment - NOT dialog_goto_url() history!
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -24,7 +25,7 @@
 
 
 static inline void
-free_history(struct list_head *history)
+free_history(LIST_OF(struct location) *history)
 {
 	while (!list_empty(*history)) {
 		struct location *loc = history->next;
@@ -35,6 +36,7 @@ free_history(struct list_head *history)
 }
 
 
+/** @relates ses_history */
 void
 create_history(struct ses_history *history)
 {
@@ -42,6 +44,7 @@ create_history(struct ses_history *history)
 	history->current = NULL;
 }
 
+/** @relates ses_history */
 void
 destroy_history(struct ses_history *history)
 {
@@ -49,6 +52,7 @@ destroy_history(struct ses_history *history)
 	history->current = NULL;
 }
 
+/** @relates ses_history */
 void
 clean_unhistory(struct ses_history *history)
 {
@@ -62,6 +66,7 @@ clean_unhistory(struct ses_history *history)
 	}
 }
 
+/** @relates ses_history */
 void
 add_to_history(struct ses_history *history, struct location *loc)
 {
@@ -74,6 +79,7 @@ add_to_history(struct ses_history *history, struct location *loc)
 	history->current = loc;
 }
 
+/** @relates ses_history */
 void
 del_from_history(struct ses_history *history, struct location *loc)
 {
@@ -175,16 +181,16 @@ go_history_by_n(struct session *ses, int n)
 	go_history(ses, loc);
 }
 
-/* See go_history() description regarding unpredictable effects on cur_loc()
+/** Go backward in the history.  See go_history() description regarding
- * by this function. */
+ * unpredictable effects on cur_loc() by this function. */
 void
 go_back(struct session *ses)
 {
 	go_history_by_n(ses, -1);
 }
 
-/* See go_history() description regarding unpredictable effects on cur_loc()
+/** Go forward in the history.  See go_history() description regarding
- * by this function. */
+ * unpredictable effects on cur_loc() by this function. */
 void
 go_unback(struct session *ses)
 {

src/session/history.h

@@ -5,13 +5,13 @@ struct location;
 struct session;
 
 struct ses_history {
-	/* The first list item is the first visited location. The last list
+	/** The first list item is the first visited location. The last list
-	 * item is the last location in the unhistory. The @current location is
+	 * item is the last location in the unhistory. The #current location is
 	 * included in this list. */
-	struct list_head history; /* -> struct location */
+	LIST_OF(struct location) history;
 
-	/* The current location. This is moveable pivot pointing somewhere at
+	/** The current location. This is moveable pivot pointing somewhere at
-	 * the middle of @history. */
+	 * the middle of #history. */
 	struct location *current;
 };
 
@@ -24,7 +24,7 @@ void add_to_history(struct ses_history *history, struct location *loc);
 void del_from_history(struct ses_history *history, struct location *loc);
 
 
-/* Note that this function is dangerous, and its results are sort of
+/** Note that this function is dangerous, and its results are sort of
  * unpredictable. If the document is cached and is permitted to be fetched from
  * the cache, the effect of this function is immediate and you end up with the
  * new location being cur_loc(). BUT if the cache entry cannot be used, the
@@ -34,7 +34,8 @@ void del_from_history(struct ses_history *history, struct location *loc);
  * after call to this function (or the regents go_(un)back(), of course). */
 void go_history(struct session *ses, struct location *loc);
 
-/* Move back -n times if n is negative, forward n times if positive. */
+/** Move back -@a n times if @a n is negative, forward @a n times if
+ * positive. */
 void go_history_by_n(struct session *ses, int n);
 
 void go_back(struct session *ses);

src/session/location.c

@@ -1,4 +1,5 @@
-/* Locations handling */
+/** Locations handling
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -14,6 +15,7 @@
 #include "util/string.h"
 
 
+/** @relates location */
 void
 copy_location(struct location *dst, struct location *src)
 {

src/session/location.h

@@ -8,7 +8,7 @@
 struct location {
 	LIST_HEAD(struct location);
 
-	struct list_head frames;
+	LIST_OF(struct frame) frames;
 	struct download download;
 	struct view_state vs;
 };
@@ -16,7 +16,8 @@ struct location {
 
 void copy_location(struct location *, struct location *);
 
-/* You probably want to call del_from_history() first! */
+/** You probably want to call del_from_history() first!
+ * @relates location */
 void destroy_location(struct location *);
 
 #endif

src/session/session.c

@@ -1,4 +1,5 @@
-/* Sessions managment - you'll find things here which you wouldn't expect */
+/** Sessions managment - you'll find things here which you wouldn't expect
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -64,7 +65,7 @@ struct file_to_load {
 	struct download download;
 };
 
-/* This structure and related functions are used to maintain information
+/** This structure and related functions are used to maintain information
  * for instances opened in new windows. We store all related session info like
  * URI and base session to clone from so that when the new instance connects
  * we can look up this information. In case of failure the session information
@@ -84,7 +85,7 @@ struct session_info {
 #define file_to_load_is_active(ftl) ((ftl)->req_sent && is_in_progress_state((ftl)->download.state))
 
 
-INIT_LIST_HEAD(sessions);
+INIT_LIST_OF(struct session, sessions);
 
 enum remote_session_flags remote_session_flags;
 
@@ -96,7 +97,7 @@ static struct file_to_load *request_additional_file(struct session *,
 static window_handler_T tabwin_func;
 
 
-static INIT_LIST_HEAD(session_info);
+static INIT_LIST_OF(struct session_info, session_info);
 static int session_info_id = 1;
 
 static struct session_info *
@@ -139,7 +140,7 @@ done_saved_session_info(void)
 		done_session_info(session_info.next);
 }
 
-/* Timer callback for @info->timer.  As explained in @install_timer,
+/** Timer callback for session_info.timer.  As explained in install_timer(),
  * this function must erase the expired timer ID from all variables.  */
 static void
 session_info_timeout(int id)
@@ -227,6 +228,7 @@ get_master_session(void)
 	return NULL;
 }
 
+/** @relates session */
 struct download *
 get_current_download(struct session *ses)
 {
@@ -440,7 +442,7 @@ load_frames(struct session *ses, struct document_view *doc_view)
 	}
 }
 
-/* Timer callback for @ses->display_timer.  As explained in @install_timer,
+/** Timer callback for session.display_timer.  As explained in install_timer(),
  * this function must erase the expired timer ID from all variables.  */
 void
 display_timer(struct session *ses)
@@ -474,7 +476,7 @@ struct questions_entry {
 	void *data;
 };
 
-INIT_LIST_HEAD(questions_queue);
+INIT_LIST_OF(struct questions_entry, questions_queue);
 
 
 void
@@ -699,9 +701,9 @@ request_additional_file(struct session *ses, unsigned char *name, struct uri *ur
 }
 
 static void
-load_additional_file(struct file_to_load *ftl, struct document_view *doc_view,
+load_additional_file(struct file_to_load *ftl, enum cache_mode cache_mode)
-		     enum cache_mode cache_mode)
 {
+	struct document_view *doc_view = current_frame(ftl->ses);
 	struct uri *referrer = doc_view && doc_view->document
 			     ? doc_view->document->uri : NULL;
 
@@ -719,15 +721,12 @@ process_file_requests(struct session *ses)
 		int more = 0;
 
 		foreach (ftl, ses->more_files) {
-			struct document_view *doc_view;
-
 			if (ftl->req_sent)
 				continue;
 
 			ftl->req_sent = 1;
 
-			doc_view = current_frame(ses);
+			load_additional_file(ftl, CACHE_MODE_NORMAL);
-			load_additional_file(ftl, doc_view, CACHE_MODE_NORMAL);
 			more = 1;
 		}
 
@@ -744,7 +743,7 @@ dialog_goto_url_open(void *data)
 	dialog_goto_url((struct session *) data, NULL);
 }
 
-/* Returns 0 if the first session was not properly initialized and
+/** @returns 0 if the first session was not properly initialized and
  * setup_session() should be called on the session as well. */
 static int
 setup_first_session(struct session *ses, struct uri *uri)
@@ -824,7 +823,7 @@ setup_first_session(struct session *ses, struct uri *uri)
 	return 0;
 }
 
-/* First load the current URI of the base session. In most cases it will just
+/** First load the current URI of the base session. In most cases it will just
  * be fetched from the cache so that the new tab will not appear ``empty' while
  * loading the real URI or showing the goto URL dialog. */
 static void
@@ -851,6 +850,7 @@ setup_session(struct session *ses, struct uri *uri, struct session *base)
 	}
 }
 
+/** @relates session  */
 struct session *
 init_session(struct session *base_session, struct terminal *term,
 	     struct uri *uri, int in_background)
@@ -978,7 +978,8 @@ init_remote_session(struct session *ses, enum remote_session_flags *remote_ptr,
 
 
 struct string *
-encode_session_info(struct string *info, struct list_head *url_list)
+encode_session_info(struct string *info,
+		    LIST_OF(struct string_list_item) *url_list)
 {
 	struct string_list_item *url;
 
@@ -993,7 +994,7 @@ encode_session_info(struct string *info, struct list_head *url_list)
 	return info;
 }
 
-/* Older elinks versions (up to and including 0.9.1) sends no magic variable and if
+/** Older elinks versions (up to and including 0.9.1) sends no magic variable and if
  * this is detected we fallback to the old session info format. For this format
  * the magic member of terminal_info hold the length of the URI string. The
  * old format is handled by the default label in the switch.
@@ -1002,12 +1003,11 @@ encode_session_info(struct string *info, struct list_head *url_list)
  * terminal_info data member. The magic variable controls how to interpret
  * the fields:
  *
- *	INTERLINK_NORMAL_MAGIC means use the terminal_info session_info
+ *    -	INTERLINK_NORMAL_MAGIC means use the terminal_info session_info
  *	variable as an id for a saved session.
  *
- *	INTERLINK_REMOTE_MAGIC means use the terminal_info session_info
+ *    -	INTERLINK_REMOTE_MAGIC means use the terminal_info session_info
  *	variable as the remote session flags. */
-
 int
 decode_session_info(struct terminal *term, struct terminal_info *info)
 {
@@ -1194,7 +1194,6 @@ reload(struct session *ses, enum cache_mode cache_mode)
 	if (have_location(ses)) {
 		struct location *loc = cur_loc(ses);
 		struct file_to_load *ftl;
-		struct document_view *doc_view = current_frame(ses);
 
 #ifdef CONFIG_ECMASCRIPT
 		loc->vs.ecmascript_fragile = 1;
@@ -1217,7 +1216,7 @@ reload(struct session *ses, enum cache_mode cache_mode)
 			ftl->download.data = ftl;
 			ftl->download.callback = (download_callback_T *) file_loading_callback;
 
-			load_additional_file(ftl, doc_view, cache_mode);
+			load_additional_file(ftl, cache_mode);
 		}
 	}
 }
@@ -1282,9 +1281,10 @@ tabwin_func(struct window *tab, struct term_event *ev)
 	}
 }
 
-/*
+/**
- * Gets the url being viewed by this session. Writes it into str.
+ * Gets the url being viewed by this session. Writes it into @a str.
- * A maximum of str_size bytes (including null) will be written.
+ * A maximum of @a str_size bytes (including null) will be written.
+ * @relates session
  */
 unsigned char *
 get_current_url(struct session *ses, unsigned char *str, size_t str_size)
@@ -1307,9 +1307,10 @@ get_current_url(struct session *ses, unsigned char *str, size_t str_size)
 	return safe_strncpy(str, struri(uri), length + 1);
 }
 
-/*
+/**
- * Gets the title of the page being viewed by this session. Writes it into str.
+ * Gets the title of the page being viewed by this session. Writes it into
- * A maximum of str_size bytes (including null) will be written.
+ * @a str.  A maximum of @a str_size bytes (including null) will be written.
+ * @relates session
  */
 unsigned char *
 get_current_title(struct session *ses, unsigned char *str, size_t str_size)
@@ -1326,9 +1327,10 @@ get_current_title(struct session *ses, unsigned char *str, size_t str_size)
 	return NULL;
 }
 
-/*
+/**
- * Gets the url of the link currently selected. Writes it into str.
+ * Gets the url of the link currently selected. Writes it into @a str.
- * A maximum of str_size bytes (including null) will be written.
+ * A maximum of @a str_size bytes (including null) will be written.
+ * @relates session
  */
 unsigned char *
 get_current_link_url(struct session *ses, unsigned char *str, size_t str_size)
@@ -1342,9 +1344,10 @@ get_current_link_url(struct session *ses, unsigned char *str, size_t str_size)
 	return safe_strncpy(str, link->where ? link->where : link->where_img, str_size);
 }
 
-/* get_current_link_name: returns the name of the current link
+/** get_current_link_name: returns the name of the current link
- * (the text between <A> and </A>), str is a preallocated string,
+ * (the text between <A> and </A>), @a str is a preallocated string,
- * str_size includes the null char. */
+ * @a str_size includes the null char.
+ * @relates session */
 unsigned char *
 get_current_link_name(struct session *ses, unsigned char *str, size_t str_size)
 {
@@ -1378,12 +1381,14 @@ get_current_link_in_view(struct document_view *doc_view)
 	return link && !link_is_form(link) ? link : NULL;
 }
 
+/** @relates session */
 struct link *
 get_current_session_link(struct session *ses)
 {
 	return get_current_link_in_view(current_frame(ses));
 }
 
+/** @relates session */
 int
 eat_kbd_repeat_count(struct session *ses)
 {

src/session/session.h

@@ -20,7 +20,7 @@ struct terminal;
 struct uri;
 struct window;
 
-/* Used by delayed_open and delayed_goto_uri_frame. */
+/** Used by delayed_open() and delayed_goto_uri_frame(). */
 struct delayed_open {
 	struct session *ses;
 	struct uri *uri;
@@ -37,7 +37,7 @@ enum remote_session_flags {
 	SES_REMOTE_INFO_BOX = 64,
 };
 
-/* This is generic frame descriptor, meaningful mainly for ses_*_frame*(). */
+/** This is generic frame descriptor, meaningful mainly for ses_*_frame*(). */
 struct frame {
 	LIST_HEAD(struct frame);
 
@@ -47,22 +47,22 @@ struct frame {
 	struct view_state vs;
 };
 
-/* Use for keyboard prefixes. */
+/** Use for keyboard prefixes. */
 struct kbdprefix {
-	/* This is the repeat count being inserted by user so far. It is stored
+	/** This is the repeat count being inserted by user so far.
-	 * intermediately per-session. */
+	 * It is stored intermediately per-session. */
 	int repeat_count;
 
 #ifdef CONFIG_MARKS
-	/* If the previous key was a mark prefix, this describes what kind of
+	/** If the previous key was a mark prefix, this describes what kind
-	 * action are we supposed to do when we receive the next key. */
+	 * of action are we supposed to do when we receive the next key. */
 	enum { KP_MARK_NOTHING, KP_MARK_SET, KP_MARK_GOTO } mark;
 #endif
 };
 
 struct session;
 
-/* This describes, what are we trying to do right now. We pass this around so
+/** This describes, what are we trying to do right now. We pass this around so
  * that we can use generic scheduler routines and when the control will get
  * back to our subsystem, we will know what are we up to. */
 enum task_type {
@@ -104,10 +104,10 @@ struct session_status {
 	struct led *ecmascript_led;
 	struct led *popup_led;
 #endif
-	/* Has the tab been visited yet. */
+	/** Has the tab been visited yet. */
 	unsigned int visited:1;
 
-	/* Is processing file requests. */
+	/** Is processing file requests. */
 	unsigned int processing_file_requests:1;
 	unsigned int show_tabs_bar_at_top:1;
 };
@@ -123,7 +123,7 @@ enum navigate_mode {
 	NAVIGATE_CURSOR_ROUTING,
 };
 
-/* This is one of the building stones of ELinks architecture --- this structure
+/** This is one of the building stones of ELinks architecture --- this structure
  * carries information about the specific ELinks session. Each tab (thus, at
  * least one per terminal, in the normal case) has its own session. Session
  * describes mainly the current browsing and control state, from the currently
@@ -133,19 +133,22 @@ struct session {
 	LIST_HEAD(struct session);
 
 
-	/* The vital session data */
+	/** @name The vital session data
+	 * @{ */
 
 	struct window *tab;
 
 
-	/* Browsing history */
+	/** @} @name Browsing history
+	 * @{ */
 
 	struct ses_history history;
 
 
-	/* The current document */
+	/** @} @name The current document
+	 * @{ */
 
-	struct list_head more_files; /* -> struct file_to_load */
+	LIST_OF(struct file_to_load) more_files;
 
 	struct download loading;
 	struct uri *loading_uri;
@@ -154,35 +157,38 @@ struct session {
 	int redirect_cnt;
 
 	struct document_view *doc_view;
-	struct list_head scrn_frames; /* -> struct document_view */
+	LIST_OF(struct document_view) scrn_frames;
 
 	struct uri *download_uri;
 
-	/* The URI which is the referrer to the current loaded document or NULL
+	/** The URI which is the referrer to the current loaded document
-	 * if there are no referrer. */
+	 * or NULL if there are no referrer.
-	/* The @referrer members sole purpose is to have the information handy
+	 *
-	 * when loading URIs. It is not 'filtered' in anyway at this level only
+	 * The @c referrer member's sole purpose is to have the information
-	 * at the lower ones. */
+	 * handy when loading URIs. It is not 'filtered' in anyway at this
+	 * level only at the lower ones. */
 	struct uri *referrer;
 
 
-	/* The current action-in-progress selector */
+	/** @} @name The current action-in-progress selector
+	 * @{ */
 
 	struct session_task task;
 
 
-	/* The current browsing state */
+	/** @} @name The current browsing state
+	 * @{ */
 
 	int search_direction;
 	struct kbdprefix kbdprefix;
 	int exit_query;
 	timer_id_T display_timer;
 
-	/* The text input form insert mode. It is a tristate controlled by the
+	/** The text input form insert mode. It is a tristate controlled by the
 	 * boolean document.browse.forms.insert_mode option. When disabled we
-	 * use mode less insertion and we always insert stuff into the text
+	 * use modeless insertion and we always insert stuff into the text
 	 * input field. When enabled it is possible to switch insertion on and
-	 * off using ACT_EDIT_ENTER and *_CANCEL. */
+	 * off using ::ACT_EDIT_ENTER and *_CANCEL. */
 	enum insert_mode insert_mode;
 
 	enum navigate_mode navigate_mode;
@@ -191,28 +197,32 @@ struct session {
 	unsigned char *last_search_word;
 
 
-	/* The possibly running type queries (what-to-do-with-that-file?) */
+	/** The possibly running type queries (what-to-do-with-that-file?) */
-	struct list_head type_queries; /* -> struct type_query */
+	LIST_OF(struct type_query) type_queries;
 
-	/* The info for status displaying */
+	/** The info for status displaying */
 	struct session_status status;
+
+	/** @} */
 };
 
-extern struct list_head sessions; /* -> struct session */
+extern LIST_OF(struct session) sessions;
 extern enum remote_session_flags remote_session_flags;
 
-/* This returns a pointer to the current location inside of the given session.
+/** This returns a pointer to the current location inside of the given session.
- * That's nice for encapsulation and alrady paid out once ;-). */
+ * That's nice for encapsulation and already paid out once ;-). */
 #define cur_loc(x) ((x)->history.current)
 
-/* Return if we have anything being loaded in this session already. */
+/** Return if we have anything being loaded in this session already.
+ * @relates session */
 static inline int
 have_location(struct session *ses) {
 	return !!cur_loc(ses);
 }
 
-/* Swaps the current session referrer with the new one passed as @referrer */
+/** Swaps the current session referrer with the new one passed as @a referrer.
-/* @referrer may be NULL */
+ * @a referrer may be NULL.
+ * @relates session */
 void set_session_referrer(struct session *ses, struct uri *referrer);
 
 void
@@ -221,13 +231,14 @@ print_error_dialog(struct session *ses, enum connection_state state,
 
 void process_file_requests(struct session *);
 
-struct string *encode_session_info(struct string *info, struct list_head *url_list);
+struct string *encode_session_info(struct string *info,
+				   LIST_OF(struct string_list_item) *url_list);
 
-/* Returns zero if the info was remote sessions or if it failed to create any
+/** @returns zero if the info was remote sessions or if it failed to
- * sessions. */
+ * create any sessions. */
 int decode_session_info(struct terminal *term, struct terminal_info *info);
 
-/* Registers a base session and returns it's id. Value <= 0 means error. */
+/** Registers a base session and returns its id. Value <= 0 means error. */
 int
 add_session_info(struct session *ses, struct uri *uri, struct uri *referrer,
 		 enum cache_mode cache_mode, enum task_type task);
@@ -248,12 +259,13 @@ struct frame *ses_find_frame(struct session *, unsigned char *);
 void free_files(struct session *);
 void display_timer(struct session *ses);
 
-/* session_is_loading() is like !!get_current_download() but doesn't take
+/** session_is_loading() is like !!get_current_download() but doesn't take
- * @req_sent into account. */
+ * session.req_sent into account.
-struct download *get_current_download(struct session *ses);
+ * @relates session */
 int session_is_loading(struct session *ses);
+struct download *get_current_download(struct session *ses);
 
-/* Information about the current document */
+/** Information about the current document */
 unsigned char *get_current_url(struct session *, unsigned char *, size_t);
 unsigned char *get_current_title(struct session *, unsigned char *, size_t);
 
@@ -262,13 +274,13 @@ struct link *get_current_link_in_view(struct document_view *doc_view);
 unsigned char *get_current_link_url(struct session *, unsigned char *, size_t);
 unsigned char *get_current_link_name(struct session *, unsigned char *, size_t);
 
-extern struct list_head questions_queue;
+extern LIST_OF(struct questions_entry) questions_queue;
 void add_questions_entry(void (*callback)(struct session *, void *), void *data);
 void check_questions_queue(struct session *ses);
 
 unsigned char *get_homepage_url(void);
 
-/* Returns current keyboard repeat count and reset it. */
+/** Returns current keyboard repeat count and reset it. */
 int eat_kbd_repeat_count(struct session *ses);
 
 #endif

src/session/task.c

@@ -1,4 +1,5 @@
-/* Sessions task management */
+/** Sessions task management
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -106,7 +107,7 @@ post_no(void *task_)
 	done_uri(task->uri);
 }
 
-/* Check if the URI is obfuscated (bug 382). The problem is said to occur when
+/** Check if the URI is obfuscated (bug 382). The problem is said to occur when
  * a URI designed to pass access a specific location with a supplied username,
  * contains misleading chars prior to the @ symbol.
  *
@@ -279,13 +280,13 @@ ses_goto(struct session *ses, struct uri *uri, unsigned char *target_frame,
 }
 
 
-/* If @loaded_in_frame is set, this was called just to indicate a move inside a
+/** If @a loaded_in_frame is set, this was called just to indicate a move inside
- * frameset, and we basically just reset the appropriate frame's view_state in
+ * a frameset, and we basically just reset the appropriate frame's view_state in
  * that case. When clicking on a link inside a frame, the frame URI is somehow
  * updated and added to the files-to-load queue, then ses_forward() is called
- * with @loaded_in_frame unset, duplicating the whole frameset's location, then
+ * with @a loaded_in_frame unset, duplicating the whole frameset's location,
- * later the file-to-load callback calls it for the particular frame with
+ * then later the file-to-load callback calls it for the particular frame with
- * @loaded_in_frame set. */
+ * @a loaded_in_frame set. */
 struct view_state *
 ses_forward(struct session *ses, int loaded_in_frame)
 {

src/session/task.h

@@ -10,8 +10,8 @@ struct terminal;
 struct view_state;
 struct uri;
 
-/* This is for map_selected(), it is used to pass around information about
+/** This is for map_selected(), it is used to pass around information
- * in-imagemap links. */
+ * about in-imagemap links. */
 struct link_def {
 	unsigned char *link;
 	unsigned char *target;

src/terminal/color.c

@@ -1,4 +1,5 @@
-/* Terminal color composing. */
+/** Terminal color composing.
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -51,11 +52,12 @@ color_distance(const struct rgb *c1, const struct rgb *c2)
 #define RGB_HASH_SIZE		4096
 #define HASH_RGB(color, l)	((RGBCOLOR(color) + (l)) & (RGB_HASH_SIZE - 1))
 
-/* Initialize a rgb struct from a color_T */
+/** Initialize a rgb struct from a color_T
+ * @relates rgb */
 #define INIT_RGB(color) \
 	{ RED_COLOR(color), GREEN_COLOR(color), BLUE_COLOR(color) }
 
-/* Locates the nearest terminal color. */
+/** Locates the nearest terminal color. */
 static inline unsigned char
 get_color(color_T color, const struct rgb *palette, int level)
 {
@@ -109,9 +111,9 @@ get_color(color_T color, const struct rgb *palette, int level)
 #undef GREEN_COLOR_MASK
 #undef BLUE_COLOR_MASK
 
-/* Controls what color ranges to use when setting the terminal color. */
+/** Controls what color ranges to use when setting the terminal color.
-/* TODO: Part of the 256 color palette is gray scale, maybe we could experiment
+ * @todo TODO: Part of the 256 color palette is gray scale, maybe we
- * with a grayscale mode. ;) --jonas */
+ * could experiment with a grayscale mode. ;) --jonas */
 enum palette_range {
        PALETTE_FULL = 0,
        PALETTE_HALF,
@@ -173,7 +175,8 @@ static const struct color_mode_info *const color_modes[] = {
 	 * only if CONFIG_TRUE_COLOR is not defined.  */
 	/* COLOR_MODE_TRUE_COLOR */ &color_mode_16,
 };
-/* Get a compile-time error if the array has the wrong size.  */
+/** Get a compile-time error if the ::color_modes array has the wrong
+ * size.  */
 typedef int assert_enough_color_modes[
 	(sizeof(color_modes) / sizeof(color_modes[0]) == COLOR_MODES)
 	? 1 : -1];
@@ -191,9 +194,11 @@ typedef int assert_enough_color_modes[
  *
  * Bright colors will be rendered bold. */
 
-/* This table is based mostly on wild guesses of mine. Feel free to
+/** Map foreground colors to more visible ones on various backgrounds.
+ * Use like: fg = fg_color[fg][bg];
+ *
+ * This table is based mostly on wild guesses of mine. Feel free to
  * correct it. --pasky */
-/* Indexed by [fg][bg]->fg: */
 static const unsigned char fg_color[16][8] = {
 	/* bk  r  gr  br  bl   m   c   w */
 
@@ -231,7 +236,7 @@ static const unsigned char fg_color[16][8] = {
 	{ 15, 15, 15, 15, 15, 15, 15, 15 },
 };
 
-/* When determining wether to use negative image we make the most significant
+/* When determining whether to use negative image we make the most significant
  * be least significant. */
 #define CMPCODE(c) (((c) << 1 | (c) >> 2) & TERM_COLOR_MASK)
 #define use_inverse(bg, fg) CMPCODE(fg & TERM_COLOR_MASK) < CMPCODE(bg)

src/terminal/color.h

@@ -21,26 +21,27 @@ struct screen_char;
 #define TERM_COLOR_FOREGROUND_16(color) ((color)[0] & TERM_COLOR_MASK)
 #define TERM_COLOR_BACKGROUND_16(color) (((color)[0] >> 4) & TERM_COLOR_MASK)
 
-/* Bit flags to control how the colors are handled. */
+/** Bit flags to control how the colors are handled. */
 enum color_flags {
-	/* Use a decreased color range. */
+	/** Use a decreased color range. */
 	COLOR_DECREASE_LIGHTNESS = 1,
 
-	/* Mangle the color to stand out if attributes like underline are set.
+	/** Mangle the color to stand out if attributes like underline are set.
-	 * Useful for terminals that doesn't support these attributes.  */
+	 * Useful for terminals that don't support these attributes.  */
 	COLOR_ENHANCE_UNDERLINE = 2,
 
-	/* Adjust the forground color to be more readable by increasing the
+	/** Adjust the foreground color to be more readable by increasing the
 	 * contrast. */
 	COLOR_INCREASE_CONTRAST = 4,
 
-	/* Adjust the contrast if the back- and foregroundcolor is equal.
+	/** Adjust the contrast if the back- and foregroundcolor is equal.
 	 * If inverting should be done also pass the latter flag. */
 	COLOR_ENSURE_CONTRAST = 8,
 	COLOR_ENSURE_INVERTED_CONTRAST = 16,
 };
 
-/* These numbers are used in the terminal._template_.colors and
+/** How many colors the terminal supports.
+ * These numbers are used in the terminal._template_.colors and
  * document.dump.color_mode options.  They should be kept stable so
  * that configuration files are portable between ELinks versions.
  * Any unsupported modes should be treated as COLOR_MODE_16.
@@ -65,10 +66,12 @@ enum color_mode {
 inline void set_term_color16(struct screen_char *schar, enum color_flags flags,
 			     unsigned char fg, unsigned char bg);
 
-/* Mixes the color pair and attributes to a terminal text color. */
+/** Mixes the color pair and attributes to a terminal text color.
-/* If @flags has masked in the COLOR_INCREASE_CONTRAST the foreground color will
+ * If @a flags has masked in the ::COLOR_INCREASE_CONTRAST the
- * be adjusted. */
+ * foreground color will be adjusted.
-/* XXX: @schar may not be NULL and is modified adding stuff like boldness. */
+ *
+ * XXX: @a schar may not be NULL and is modified adding stuff like
+ * boldness. */
 void set_term_color(struct screen_char *schar, struct color_pair *pair,
 		    enum color_flags flags, enum color_mode mode);
 

src/terminal/draw.c

@@ -1,4 +1,5 @@
-/* Public terminal drawing API. Frontend for the screen image in memory. */
+/** Public terminal drawing API. Frontend for the screen image in memory.
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -15,7 +16,7 @@
 #include "util/color.h"
 #include "util/box.h"
 
-/* Makes sure that @x and @y are within the dimensions of the terminal. */
+/** Makes sure that @a x and @a y are within the dimensions of the terminal. */
 #define check_range(term, x, y) \
 	do { \
 		int_bounds(&(x), 0, (term)->width - 1); \
@@ -104,7 +105,7 @@ draw_char_color(struct terminal *term, int x, int y, struct color_pair *color)
 	set_screen_dirty(term->screen, y, y);
 }
 
-/* The data parameter here is like screen_char.data: UCS-4 if the
+/*! The @a data parameter here is like screen_char.data: UCS-4 if the
  * charset of the terminal is UTF-8 (possible only if CONFIG_UTF8 is
  * defined), and a byte otherwise.  */
 void
@@ -139,8 +140,8 @@ draw_char_data(struct terminal *term, int x, int y, unsigned char data)
 	set_screen_dirty(term->screen, y, y);
 }
 
-/* Updates a line in the terms screen. */
+/*! Used by viewer to copy over a document.
-/* When doing frame drawing @x can be different than 0. */
+ * When doing frame drawing @a x can be different than 0. */
 void
 draw_line(struct terminal *term, int x, int y, int l, struct screen_char *line)
 {
@@ -258,8 +259,10 @@ draw_border(struct terminal *term, struct box *box,
 }
 
 #ifdef CONFIG_UTF8
-/* Checks cells left and right to the box for broken double-width chars.
+/** Checks cells left and right to the box for broken double-width chars.
  * Replace it with UCS_ORPHAN_CELL.
+ *
+ * @verbatim
  * 1+---+3
  * 1|box|##4
  * 1|   |##4
@@ -267,6 +270,7 @@ draw_border(struct terminal *term, struct box *box,
  * 1+---+##4
  *   2#####4
  * 1,2,3,4 - needs to be checked, # - shadow , +,-,| - border
+ * @endverbatim
  */
 void
 fix_dwchar_around_box(struct terminal *term, struct box *box, int border,

src/terminal/draw.h

@@ -7,6 +7,7 @@ struct color_pair;
 struct box;
 struct terminal;
 
+/** How many bytes we need for the colors of one character cell.  */
 #if defined(CONFIG_TRUE_COLOR)
 /* 0, 1, 2 - rgb foreground; 3, 4, 5 - rgb background */
 #define SCREEN_COLOR_SIZE	6
@@ -17,8 +18,10 @@ struct terminal;
 #define SCREEN_COLOR_SIZE	1
 #endif
 
-/* All attributes should fit inside an unsigned char. */
+/** Attributes of a character on the screen.
-/* XXX: The bold mask is used as part of the color encoding. */
+ * All attributes should fit inside an unsigned char.
+ *
+ * XXX: The bold mask is used as part of the color encoding. */
 enum screen_char_attr {
 	SCREEN_ATTR_UNSEARCHABLE = 0x01,
 	SCREEN_ATTR_BOLD	= 0x08,
@@ -28,41 +31,44 @@ enum screen_char_attr {
 	SCREEN_ATTR_FRAME	= 0x80,
 };
 
-/* One position in the terminal screen's image. */
+/** One position in the terminal screen's image. */
 struct screen_char {
-	/* Contains either character value or frame data.
+	/** Contains either character value or frame data.
-	 * If @attr includes SCREEN_ATTR_FRAME, then @data is enum
+	 * - If #attr includes ::SCREEN_ATTR_FRAME, then @c data is
-	 * border_char; otherwise, @data is a character value.
+	 *   enum border_char.
-	 * If the charset of the terminal is UTF-8 (which is possible
+	 * - Otherwise, if the charset of the terminal is UTF-8, then
-	 * only if CONFIG_UTF8 is defined), then the character value
+	 *   @c data is a character value in UCS-4.  This is possible
-	 * is in UCS-4; otherwise, the charset is assumed to be
+	 *   only if CONFIG_UTF8 is defined.
-	 * unibyte, and the character value is a byte in that
+	 * - Otherwise, the charset of the terminal is assumed to be
-	 * charset.  */
+	 *   unibyte, and @c data is a byte in that charset.  */
 #ifdef CONFIG_UTF8
 	unicode_val_T data;
 #else
 	unsigned char data;
 #endif /* CONFIG_UTF8 */
 
-	/* Attributes are screen_char_attr bits. */
+	/** Attributes are ::screen_char_attr bits. */
 	unsigned char attr;
 
-	/* The fore- and background color. */
+	/** The fore- and background color. */
 	unsigned char color[SCREEN_COLOR_SIZE];
 };
 
+/** @relates screen_char */ 
 #define copy_screen_chars(to, from, amount) \
 	do { memcpy(to, from, (amount) * sizeof(struct screen_char)); } while (0)
 
-/* Linux frame symbols table (it's magically converted to other terminals when
+/** @name Linux frame symbols table.
- * needed). */
+ * It is magically converted to other terminals when needed.
-/* In the screen image, they have attribute SCREEN_ATTR_FRAME; you should drop them
+ * In the screen image, they have attribute SCREEN_ATTR_FRAME;
- * to the image using draw_border_char(). */
+ * you should drop them to the image using draw_border_char().
-/* TODO: When we'll support internal Unicode, this should be changed to some
+ *
- * Unicode sequences. --pasky */
+ * \todo TODO: When we'll support internal Unicode, this should be
-
+ * changed to some Unicode sequences. --pasky
-/* Codes extracted from twin-0.4.6 GPL project, a Textmode WINdow environment,
+ *
- * by Massimiliano Ghilardi http://linuz.sns.it/~max/ */
+ * Codes extracted from twin-0.4.6 GPL project, a Textmode WINdow environment,
+ * by Massimiliano Ghilardi http://linuz.sns.it/~max/
+ * @{ */
 
 /* Not yet used
 #define T_UTF_16_BOX_DRAWINGS_LIGHT_VERTICAL	0x2502
@@ -149,6 +155,9 @@ struct screen_char {
 #define T_CP437_BOX_DRAWINGS_LIGHT_UP_AND_LEFT	0x00D9
 #define T_CP437_BOX_DRAWINGS_LIGHT_DOWN_AND_RIGHT	0x00DA
 
+/** @} */
+
+
 #define BD_LIGHT(XXX)  T_CP437_BOX_DRAWINGS_LIGHT_##XXX
 #define BD_DOUBLE(XXX) T_CP437_BOX_DRAWINGS_DOUBLE_##XXX
 #define BD_MIXED(XXX) 	T_CP437_BOX_DRAWINGS_##XXX
@@ -213,29 +222,29 @@ enum border_cross_direction {
 	BORDER_X_UP
 };
 
-/* Extracts a char from the screen. */
+/** Extracts a char from the screen. */
 struct screen_char *get_char(struct terminal *, int x, int y);
 
-/* Sets the color of a screen position. */
+/** Sets the color of a screen position. */
 void draw_char_color(struct terminal *term, int x, int y,
 		     struct color_pair *color);
 
-/* Sets the data of a screen position. */
+/** Sets the data of a screen position. */
 #ifdef CONFIG_UTF8
 void draw_char_data(struct terminal *term, int x, int y, unicode_val_T data);
 #else
 void draw_char_data(struct terminal *term, int x, int y, unsigned char data);
 #endif /* CONFIG_UTF8 */
 
-/* Sets the data to @border and of a screen position. */
+/** Sets the data to @a border and of a screen position. */
 void draw_border_char(struct terminal *term, int x, int y,
 		      enum border_char border, struct color_pair *color);
 
-/* Sets the cross position of two borders. */
+/** Sets the cross position of two borders. */
 void draw_border_cross(struct terminal *, int x, int y,
 		       enum border_cross_direction, struct color_pair *color);
 
-/* Draws a char. */
+/** Draws a char. */
 #ifdef CONFIG_UTF8
 void draw_char(struct terminal *term, int x, int y,
 	       unicode_val_T data, enum screen_char_attr attr,
@@ -246,16 +255,17 @@ void draw_char(struct terminal *term, int x, int y,
 	       struct color_pair *color);
 #endif /* CONFIG_UTF8 */
 
-/* Draws area defined by @box using the same colors and attributes. */
+/** Draws area defined by @a box using the same colors and attributes. */
 void draw_box(struct terminal *term, struct box *box,
 	      unsigned char data, enum screen_char_attr attr,
 	      struct color_pair *color);
 
-/* Draws a shadow of @width and @height with color @color around @box. */
+/** Draws a shadow of @a width and @a height with color @a color
+ * around @a box. */
 void draw_shadow(struct terminal *term, struct box *box,
 		 struct color_pair *color, int width, int height);
 
-/* Draw borders. */
+/** Draw borders. */
 void draw_border(struct terminal *term, struct box *box,
 		 struct color_pair *color, int width);
 
@@ -264,23 +274,22 @@ void fix_dwchar_around_box(struct terminal *term, struct box *box, int border,
 			   int shadow_width, int shadow_height);
 #endif /* CONFIG_UTF8 */
 
-/* Draws @length chars from @text. */
+/** Draws @a length chars from @a text. */
 void draw_text(struct terminal *term, int x, int y,
 	       unsigned char *text, int length,
 	       enum screen_char_attr attr,
 	       struct color_pair *color);
 
-/* Draws @length chars from @line on the screen. */
+/** Draws @a length chars from @a line on the screen.  */
-/* Used by viewer to copy over a document. */
 void draw_line(struct terminal *term, int x, int y, int length,
 	       struct screen_char *line);
 
-/* Updates the terminals cursor position. When @blockable is set the
+/** Updates the terminals cursor position. When @a blockable is set the
  * block_cursor terminal option decides whether the cursor should be put at the
  * bottom right corner of the screen. */
 void set_cursor(struct terminal *term, int x, int y, int blockable);
 
-/* Blanks the screen. */
+/** Blanks the screen. */
 void clear_terminal(struct terminal *);
 
 #endif

src/terminal/event.c

@@ -1,4 +1,5 @@
-/* Event system support routines. */
+/** Event system support routines.
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -33,18 +34,19 @@
 #include "viewer/timer.h"
 
 
-/* Information used for communication between ELinks instances */
+/** Information used for communication between ELinks instances */
 struct terminal_interlink {
-	/* How big the input queue is and how much is free */
+	/** How big the input queue is */
 	int qlen;
+	/** How much is free */
 	int qfreespace;
 
-	/* UTF8 input key value decoding data. */
+	/** UTF-8 input key value decoding data. */
 	struct {
 		unicode_val_T ucs;
 		int len;
 		unicode_val_T min;
-		/* Modifier keys from the key event that carried the
+		/** Modifier keys from the key event that carried the
 		 * first byte of the character.  We need this because
 		 * ELinks sees e.g. ESC U+00F6 as 0x1B 0xC3 0xB6 and
 		 * converts it to Alt-0xC3 0xB6, attaching the
@@ -52,8 +54,8 @@ struct terminal_interlink {
 		term_event_modifier_T modifier;
 	} utf8;
 
-	/* This is the queue of events as coming from the other ELinks instance
+	/** This is the queue of events as coming from the other
-	 * owning the hosting terminal. */
+	 * ELinks instance owning the hosting terminal. */
 	unsigned char input_queue[1];
 };
 

src/terminal/event.h

@@ -12,6 +12,7 @@ struct terminal;
 #define MAX_CWD_LEN	256	/* this must be multiple of 8! (alignment problems) */
 
 
+/** Type of an event received from a terminal.  */
 enum term_event_type {
 	EVENT_INIT,
 	EVENT_KBD,
@@ -21,34 +22,40 @@ enum term_event_type {
 	EVENT_ABORT,
 };
 
+/** An event received from a terminal.  This type can be changed
+ * without breaking interlink compatibility.  */
 struct term_event {
 	enum term_event_type ev;
 
 	union {
-		/* EVENT_MOUSE */
+		/** ::EVENT_MOUSE */
 		struct term_event_mouse mouse;
 
-		/* EVENT_KBD */
+		/** ::EVENT_KBD */
 		struct term_event_keyboard keyboard;
 
-		/* EVENT_INIT, EVENT_RESIZE, EVENT_REDRAW */
+		/** ::EVENT_INIT, ::EVENT_RESIZE, ::EVENT_REDRAW */
 		struct term_event_size {
 			int width, height;
 		} size;
 	} info;
 };
 
+/** An event transferred via the interlink socket.  This is quite
+ * similar to struct term_event but has a different format for
+ * keyboard events.  If you change this type, you can break interlink
+ * compatibility.  */
 struct interlink_event {
 	enum term_event_type ev;
 
 	union {
-		/* EVENT_MOUSE */
+		/* ::EVENT_MOUSE */
 		struct interlink_event_mouse mouse;
 
-		/* EVENT_KBD */
+		/* ::EVENT_KBD */
 		struct interlink_event_keyboard keyboard;
 
-		/* EVENT_INIT, EVENT_RESIZE, EVENT_REDRAW */
+		/* ::EVENT_INIT, ::EVENT_RESIZE, ::EVENT_REDRAW */
 #define interlink_event_size term_event_size
 		struct interlink_event_size size;
 	} info;
@@ -79,10 +86,12 @@ set_kbd_term_event(struct term_event *ev, int key,
 	kbd_set(&ev->info.keyboard, key, modifier);
 }
 
-/* @key can be either an 8-bit byte or a value from enum term_event_special_key.
+/** Initialize @c ev as an interlink keyboard event.
- * In the latter case, this function negates the value, unless it is KBD_UNDEF.
+ * @a key can be either an 8-bit byte or a value from enum
- * For example, key == KBD_ENTER results in ev->info.keyboard.key = -KBD_ENTER.
+ * term_event_special_key.  In the latter case, this function negates
- * This mapping keeps the interlink protocol compatible with ELinks 0.11.  */
+ * the value, unless it is KBD_UNDEF.  For example, key == KBD_ENTER
+ * results in ev->info.keyboard.key = -KBD_ENTER.  This mapping keeps
+ * the interlink protocol compatible with ELinks 0.11.  */
 static inline void
 set_kbd_interlink_event(struct interlink_event *ev, int key,
 			term_event_modifier_T modifier)
@@ -126,32 +135,34 @@ set_wh_interlink_event(struct interlink_event *ev, enum term_event_type type, in
 #define set_resize_interlink_event(ev, w, h) set_wh_interlink_event(ev, EVENT_RESIZE, w, h)
 
 
-/* This holds the information used when handling the initial connection between
+/** This holds the information used when handling the initial
- * a dumb and master terminal. */
+ * connection between a dumb and master terminal.
-/* XXX: We might be connecting to an older ELinks or an older ELinks is
+ *
+ * XXX: We might be connecting to an older ELinks or an older ELinks is
  * connecting to a newer ELinks master so for the sake of compatibility it
  * would be unwise to just change the layout of the struct. If you do have to
  * add new members add them at the bottom and use magic variables to
  * distinguish them when decoding the terminal info. */
 struct terminal_info {
-	struct interlink_event event;		/* The EVENT_INIT event */
+	struct interlink_event event;		/**< The ::EVENT_INIT event */
-	unsigned char name[MAX_TERM_LEN];	/* $TERM environment name */
+	unsigned char name[MAX_TERM_LEN];	/**< $TERM environment name */
-	unsigned char cwd[MAX_CWD_LEN];		/* Current working directory */
+	unsigned char cwd[MAX_CWD_LEN];		/**< Current working directory */
-	int system_env;				/* System info (X, screen) */
+	int system_env;				/**< System info (X, screen) */
-	int length;				/* Length of @data member */
+	int length;				/**< Length of #data member */
-	int session_info;			/* Value depends on @magic */
+	int session_info;			/**< Value depends on #magic */
-	int magic;				/* Identity of the connector */
+	int magic;				/**< Identity of the connector */
 
-	/* In the master that is connected to all bytes after @data will be
+	/** In the master that is connected to all bytes after @c data
-	 * interpreted as URI string information. */
+	 * will be interpreted as URI string information. */
 	unsigned char data[1];
 };
 
-/* The @data member has to have size of one for portability but it can be
+/** The terminal_info.data member has to have size of one for
- * empty/zero so when reading and writing it we need to ignore the byte. */
+ * portability but it can be empty/zero so when reading and writing it
+ * we need to ignore the byte. */
 #define TERMINAL_INFO_SIZE offsetof(struct terminal_info, data)
 
-/* We use magic numbers to signal the identity of the dump client terminal.
+/** We use magic numbers to signal the identity of the dump client terminal.
  * Magic numbers are composed by the INTERLINK_MAGIC() macro. It is a negative
  * magic to be able to distinguish the oldest format from the newer ones. */
 #define INTERLINK_MAGIC(major, minor) -(((major) << 8) + (minor))
@@ -162,7 +173,8 @@ struct terminal_info {
 void term_send_event(struct terminal *, struct term_event *);
 void in_term(struct terminal *);
 
-/* For keyboard events handling */
+/** @name For keyboard events handling
+ * @{ */
 #define get_kbd_key(event)		(kbd_get_key(&(event)->info.keyboard))
 #define check_kbd_key(event, key)	(kbd_key_is(&(event)->info.keyboard, (key)))
 
@@ -171,9 +183,11 @@ void in_term(struct terminal *);
 
 #define check_kbd_textinput_key(event)	(get_kbd_key(event) >= ' ' && check_kbd_modifier(event, KBD_MOD_NONE))
 #define check_kbd_label_key(event)	(get_kbd_key(event) > ' ' && (check_kbd_modifier(event, KBD_MOD_NONE) || check_kbd_modifier(event, KBD_MOD_ALT)))
+/** @} */
 
 
-/* For mouse events handling */
+/** @name For mouse events handling
+ * @{ */
 #define get_mouse_action(event)		 (mouse_get_action(&(event)->info.mouse))
 #define check_mouse_action(event, value) (mouse_action_is(&(event)->info.mouse, (value)))
 
@@ -183,6 +197,7 @@ void in_term(struct terminal *);
 
 #define check_mouse_position(event, box) \
 	mouse_is_in_box(&(event)->info.mouse, box)
+/** @} */
 
 
 #endif /* EL__TERMINAL_EVENT_H */

src/terminal/hardio.c

@@ -1,4 +1,5 @@
-/* Low-level terminal-suitable I/O routines */
+/** Low-level terminal-suitable I/O routines
+ * @file */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"

src/terminal/itrm.h

@@ -4,7 +4,7 @@
 
 #define ITRM_OUT_QUEUE_SIZE	16384
 
-/* Currently, ELinks treats control sequences as text if they are
+/** Currently, ELinks treats control sequences as text if they are
  * longer than ITRM_IN_QUEUE_SIZE bytes.  So it should be defined
  * as greater than the length of any control sequence that ELinks
  * is expected to receive.  These are the longest so far:
@@ -15,44 +15,44 @@
 struct itrm_queue {
 	unsigned char *data;
 
-	/* The amount of data in the queue, in bytes.  This may be
+	/** The amount of data in the queue, in bytes.  This may be
 	 * less than the amount of memory allocated for the buffer;
 	 * struct itrm_queue does not keep track of that, and has
 	 * no global policy on whether the buffer can be resized.  */
 	int len;
 };
 
-/* Things coming into an itrm, whether from the terminal or from the
+/** Things coming into an itrm, whether from the terminal or from the
  * master.  */
 struct itrm_in {
-	/* A file descriptor for the standard input.  In some ports,
+	/** A file descriptor for the standard input.  In some ports,
 	 * this is the terminal device itself; in others, this is a
 	 * pipe from an input thread.  In principle, the data format
 	 * depends on the terminal.  */
 	int std;
 
-	/* In a slave process, a file descriptor for a socket from
+	/** In a slave process, a file descriptor for a socket from
 	 * which it reads data sent by the master process.  The other
 	 * end of the socket connection is terminal.fdout in the
 	 * master process.  The format of these data is almost the
-	 * same as could be sent to the terminal (via itrm.out.std),
+	 * same as could be sent to the terminal (via itrm_out.std),
 	 * but there are special commands that begin with a null byte.
 	 *
-	 * In the master process, @sock is the same as itrm.out.std,
+	 * In the master process, @c sock is the same as itrm_out.std,
 	 * but nothing actually uses it.  */
 	int sock;
 
-	/* A file descriptor for controlling the standard input.  This
+	/** A file descriptor for controlling the standard input.  This
-	 * is always the terminal device itself, thus the same as @std
+	 * is always the terminal device itself, thus the same as #std
 	 * in some ports.  ELinks doesn't read or write with this file
-	 * descriptor; it only does things like tcsetattr.  */
+	 * descriptor; it only does things like tcsetattr().  */
 	int ctl;
 
-	/* Bytes that have been received from @std but not yet
+	/** Bytes that have been received from #std but not yet
-	 * converted to events.  queue.data is allocated for
+	 * converted to events.  itrm_queue.data is allocated for
-	 * ITRM_IN_QUEUE_SIZE bytes and never resized.  The itrm
+	 * ::ITRM_IN_QUEUE_SIZE bytes and never resized.  The itrm
 	 * layer cannot parse control sequences longer than that.
-	 * Anything that modifies queue.len should also call
+	 * Anything that modifies itrm_queue.len should also call
 	 * unhandle_itrm_stdin() if the queue becomes full, or
 	 * handle_itrm_stdin() if the queue stops being full.
 	 * Those functions are internal to kbd.c.  */
@@ -62,14 +62,14 @@ struct itrm_in {
 /* Things going out from an itrm, whether to the terminal or to the
  * master.  */
 struct itrm_out {
-	/* A file descriptor for the standard output.  In some ports,
+	/** A file descriptor for the standard output.  In some ports,
 	 * this is the terminal device itself; in others, this is a
 	 * pipe to an output thread.  The data format depends on the
 	 * terminal in principle, but this has not yet been
 	 * implemented; see bug 96.  */
 	int std;
 
-	/* A file descriptor for a pipe or socket to which this
+	/** A file descriptor for a pipe or socket to which this
 	 * process sends input events.  The other end of the pipe or
 	 * socket connection is terminal.fdin in the master process.
 	 * If the connection is from the master process to itself, it
@@ -79,36 +79,36 @@ struct itrm_out {
 	 * sent.  */
 	int sock;
 
-	/* Bytes that should be written to @sock.  They will be
+	/** Bytes that should be written to #sock.  They will be
 	 * written when select() indicates the write won't block.  To
 	 * add data here, call itrm_queue_event(), which reallocates
-	 * queue.data if appropriate.  The size of this queue is
+	 * itrm_queue.data if appropriate.  The size of this queue is
-	 * unrelated to ITRM_OUT_QUEUE_SIZE.  */
+	 * unrelated to ::ITRM_OUT_QUEUE_SIZE.  */
 	struct itrm_queue queue;
 };
 
-/* A connection between a terminal and a master ELinks process.
+/** A connection between a terminal and a master ELinks process.
  * Normally, only one struct itrm exists in each master or slave
- * process, and the global pointer @ditrm (not declared here)
+ * process, and the global pointer ::ditrm (not declared here)
  * points to it.  */
 struct itrm {
-	struct itrm_in in;		/* Input */
+	struct itrm_in in;		/**< Input */
-	struct itrm_out out;		/* Output */
+	struct itrm_out out;		/**< Output */
 
-	timer_id_T timer;		/* ESC timeout timer */
+	timer_id_T timer;		/**< ESC timeout timer */
-	struct termios t;		/* For restoring original attributes */
+	struct termios t;		/**< For restoring original attributes */
-	void *mouse_h;			/* Mouse handle */
+	void *mouse_h;			/**< Mouse handle */
-	unsigned char *orig_title;	/* For restoring window title */
+	unsigned char *orig_title;	/**< For restoring window title */
 
-	unsigned int blocked:1;		/* Whether it was blocked */
+	unsigned int blocked:1;		/**< Whether it was blocked */
-	unsigned int altscreen:1;	/* Whether to use alternate screen */
+	unsigned int altscreen:1;	/**< Whether to use alternate screen */
-	unsigned int touched_title:1;	/* Whether the term title was changed */
+	unsigned int touched_title:1;	/**< Whether the term title was changed */
-	/* The @remote flag is not set in regular slave terminals.
+	/*! The @c remote flag is not set in regular slave terminals.
 	 * Instead, it means the itrm controls a preexisting terminal,
 	 * and windows should not be displayed on the terminal of the
 	 * itrm (but see bug 776: the master clears the terminal anyway);
 	 * thus the terminal init and done strings are not sent.  */
-	unsigned int remote:1;		/* Whether it is a remote session */
+	unsigned int remote:1;		/**< Whether it is a remote session */
 };
 
 #endif