1
0
mirror of https://github.com/rkd77/elinks.git synced 2024-06-17 23:55:32 +00:00

Doxygenate src/document/ (but not subdirs)

This commit is contained in:
Kalle Olavi Niemitalo 2007-07-27 19:45:02 +03:00 committed by Kalle Olavi Niemitalo
parent 4231b9d8d8
commit a26db3948a
10 changed files with 118 additions and 88 deletions

View File

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

View File

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

View File

@ -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
* screen. */
/** The document line consisting of the chars ready to be copied to
* the terminal screen. */
struct line {
struct screen_char *chars;
int length;
};
/* Codepage status */
/** Codepage status */
enum cp_status {
CP_STATUS_NONE,
CP_STATUS_SERVER,
@ -83,18 +83,18 @@ struct link {
unsigned char *where_img;
unsigned char *title;
/* The set of characters belonging to this link (their coordinates
* in the document) - each character has own {struct point}. */
/** The set of characters belonging to this link (their coordinates
* in the document) - each character has own struct point. */
struct point *points;
int npoints;
int number;
/* This is supposed to be the colour-pair of the link, but the actual
/** This is supposed to be the colour-pair of the link, but the actual
* colours on the canvas can differ--e.g., with image links. */
struct color_pair color;
/* XXX: They don't neccessary need to be link-specific, but we just
/*! XXX: They don't neccessary need to be link-specific, but we just
* don't support them for any other elements for now. Well, we don't
* even have a good place where to store them in that case. */
LIST_OF(struct script_event_hook) *event_hooks;
@ -143,26 +143,26 @@ struct document {
LIST_OF(struct node) nodes;
#ifdef CONFIG_ECMASCRIPT
/* ECMAScript snippets to be executed during loading the document into
/** ECMAScript snippets to be executed during loading the document into
* a window. This currently involves <script>s and onLoad handlers.
* Note that if you hit a string beginning by '^' here, it is followed
* by an external reference - you must wait with processing other items
* until it gets resolved and loaded. New items are guaranteed to
* always appear at the list end. */
LIST_OF(struct string_list_item) onload_snippets;
/* FIXME: We should externally maybe using cache_entry store the
/** \todo FIXME: We should externally maybe using cache_entry store the
* dependencies between the various entries so nothing gets removed
* unneeded. */
struct uri_list ecmascript_imports;
/* used by setTimeout */
/** used by setTimeout */
timer_id_T timeout;
#endif
#ifdef CONFIG_CSS
/* FIXME: We should externally maybe using cache_entry store the
/** \todo FIXME: We should externally maybe using cache_entry store the
* dependencies between the various entries so nothing gets removed
* unneeded. */
struct uri_list css_imports;
/* Calculated from the id's of all the cache entries in css_imports.
/** Calculated from the id's of all the cache entries in #css_imports.
* Used for checking rerendering for available CSS imports. */
unsigned long css_magic;
#endif
@ -172,15 +172,17 @@ struct document {
struct cache_entry *cached;
struct frame_desc *frame;
struct frameset_desc *frame_desc; /* RENAME ME */
struct frameset_desc *frame_desc; /**< \todo RENAME ME */
struct document_refresh *refresh;
struct line *data;
struct link *links;
/* Arrays with one item per rendered document's line. */
struct link **lines1; /* The first link on the line. */
struct link **lines2; /* The last link on the 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 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. */
/* Return NULL on allocation failure. */
/** Initializes a document and its canvas.
* @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. */

View File

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

View File

@ -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.
* However @form_num and @form_end also stores information about where
/** The value of @c form_num serves both as a unique ID of the form.
* 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
* 0 to INT_MAX. When a new form is added the range is partitioned so
* the forms each has unique source ranges. */
* Initially the range between @c form_num and #form_end will
* stretch from 0 to INT_MAX. When a new form is added the
* range is partitioned so the forms each has unique source
* ranges. */
int form_num;
int form_end;
int form_end; /**< @see #form_num */
unsigned char *action;
unsigned char *name;
@ -76,20 +77,20 @@ struct form_control {
struct form *form;
int g_ctrl_num;
/* The value of @position is relative to the place of the form item in
* the source. */
/** The value of @c position is relative to the place of the
* 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
* is in the charset of the document.
*
* For FC_FILE: The parser does not set @default_value. */
/** Default value, cannot be changed by document scripts.
* - 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 @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.
* (That charset can be UTF-8 only if CONFIG_UTF8 is defined,
* and is assumed to be unibyte otherwise.) The charset of
* the document and the UTF-8 I/O option have no effect
* here. */
/** Labels in a selection menu.
* - For ::FC_SELECT: @c labels are in the charset of the terminal.
* (That charset can be UTF-8 only if CONFIG_UTF8 is defined,
* and is assumed to be unibyte otherwise.) The charset of
* the document and the UTF-8 I/O option have no effect here. */
unsigned char **labels;
struct menu_item *menu;
};

View File

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

View File

@ -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
* only compare it if @needs_height is set.
*/
* <dd>Only documents containing textarea or frames uses it and we
* 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 */
/* This is mostly here to make use of this option cache so link
* drawing is faster. --jonas */
/** Active link coloring.
* This is mostly here to make use of this option cache so
* 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.
* Note that the framename is dynamically allocated. */
/** Copies the values of one struct @a from to the other @a to.
* 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);

View File

@ -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,
* this function must erase the expired timer ID from all variables. */
/** Timer callback for document_refresh.timer. As explained in
* install_timer(), this function must erase the expired timer ID from
* all variables. */
static void
do_document_refresh(void *data)
{

View File

@ -1,4 +1,5 @@
/* HTML renderer */
/** HTML renderer
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -40,12 +41,12 @@
#ifdef CONFIG_ECMASCRIPT
/* XXX: This function is de facto obsolete, since we do not need to copy
/** @todo XXX: This function is de facto obsolete, since we do not need to copy
* snippets around anymore (we process them in one go after the document is
* loaded; gradual processing was practically impossible because the snippets
* could reorder randomly during the loading - consider i.e.
* <body onLoad><script></body>: first just <body> is loaded, but then the
* rest of the document is loaded and <script> gets before <body>; do not even
* @<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
* 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 */

View File

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