aniani/elinks
1
0
Fork 0
mirror of https://github.com/rkd77/elinks.git synced 2024-06-21 00:25:37 +00:00
Code

Doxygenate src/document/ (but not subdirs)

Browse Source
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/document/docdata.c
View File

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

3
src/document/document.c
View File

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

59
src/document/document.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. */

3
src/document/forms.c
View File

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

37
src/document/forms.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;
};

3
src/document/options.c
View File

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

77
src/document/options.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);

8
src/document/refresh.c
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)
{

9
src/document/renderer.c
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 */

4
src/document/view.h
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;
};