Doxygenate src/document/css/

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,7 +101,7 @@ 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] = {
 	/* CSS_PT_NONE */		NULL,
 	/* CSS_PT_BACKGROUND */		css_apply_background_color,
@@ -113,7 +115,7 @@ 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,

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,10 +11,7 @@ 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. */
-
-/* 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,
@@ -20,13 +20,13 @@ get_css_selector_for_element(struct html_context *html_context,
 			     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,

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"
@@ -109,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>
@@ -123,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,
@@ -223,12 +228,18 @@ reparent_selector(LIST_OF(struct css_selector) *sels,
 	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,
@@ -464,10 +475,14 @@ 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)

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,20 +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
- * in case it recognized a property in the given string, or zero in case of an
- * error. */
 void css_parse_properties(LIST_OF(struct css_property) *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"

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,28 +29,32 @@
  * 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 */
 
 
-/* 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. */
+ * 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.
+ * Selectors are currently kept in lists that find_css_selector() then
- * --pasky */
+ * 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.  */
 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. */
 	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;
 	LIST_OF(struct css_selector) leaves;
 
@@ -56,7 +63,7 @@ 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;
 
@@ -68,43 +75,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 list of basic element selectors (which can then somehow
+	/** The list of basic element selectors (which can then somehow
 	 * tree up on inside). */
 	LIST_OF(struct css_selector) 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, { D_LIST_HEAD(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
  * list, or NULL. */
 struct css_selector *get_css_selector(LIST_OF(struct css_selector) *selector_list,
                                       enum css_selector_type type,
@@ -115,8 +122,8 @@ struct css_selector *get_css_selector(LIST_OF(struct css_selector) *selector_lis
 	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 list of selectors. */
+ * the given list of selectors. */
 struct css_selector *find_css_selector(LIST_OF(struct css_selector) *selector_list,
                                        enum css_selector_type type,
                                        enum css_selector_relation rel,
@@ -125,24 +132,24 @@ struct css_selector *find_css_selector(LIST_OF(struct css_selector) *selector_li
 #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(LIST_OF(struct css_selector) *selector_list,
                                        enum css_selector_type type,
                                        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,
                              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);
 
-/* 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);
 
 #ifdef DEBUG_CSS
-/* Dumps the selector tree to stderr. */
+/** Dumps the selector tree to stderr. */
 void dump_css_selector_tree(LIST_OF(struct css_selector) *selector_list);
 #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);