From d5f2d906112d0371c2de525fffeba47baa6b381e Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Fri, 27 Jul 2007 03:07:39 +0300 Subject: [PATCH] Doxygenate src/session/ --- src/session/download.c | 12 +++--- src/session/download.h | 14 +++---- src/session/history.c | 11 +++--- src/session/history.h | 13 ++++--- src/session/location.c | 3 +- src/session/location.h | 2 +- src/session/session.c | 44 ++++++++++----------- src/session/session.h | 86 +++++++++++++++++++++++------------------- src/session/task.c | 15 ++++---- src/session/task.h | 4 +- 10 files changed, 109 insertions(+), 95 deletions(-) diff --git a/src/session/download.c b/src/session/download.c index 664df1621..56d58c8a3 100644 --- a/src/session/download.c +++ b/src/session/download.c @@ -1,4 +1,5 @@ -/* Downloads managment */ +/** Downloads managment + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -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 - * want to use this function for frames as well (now, when frame has content - * type text/plain, it is ignored and displayed as HTML). */ +/** @bug FIXME: We need to modify this function to take frame data + * instead, as we want to use this function for frames as well (now, + * when frame has content type text/plain, it is ignored and displayed + * as HTML). */ void tp_display(struct type_query *type_query) { diff --git a/src/session/download.h b/src/session/download.h index e14e0e755..79923d2ef 100644 --- a/src/session/download.h +++ b/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,24 +67,24 @@ 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 LIST_OF(struct file_download) downloads; static inline int diff --git a/src/session/history.c b/src/session/history.c index bde11e020..7c22c86ea 100644 --- a/src/session/history.c +++ b/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" @@ -175,16 +176,16 @@ go_history_by_n(struct session *ses, int n) go_history(ses, loc); } -/* See go_history() description regarding unpredictable effects on cur_loc() - * by this function. */ +/** Go backward in the history. See go_history() description regarding + * 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() - * by this function. */ +/** Go forward in the history. See go_history() description regarding + * unpredictable effects on cur_loc() by this function. */ void go_unback(struct session *ses) { diff --git a/src/session/history.h b/src/session/history.h index ba5959f41..ed28bf4ae 100644 --- a/src/session/history.h +++ b/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 - * item is the last location in the unhistory. The @current location is + /** The first list item is the first visited location. The last list + * item is the last location in the unhistory. The #current location is * included in this list. */ LIST_OF(struct location) history; - /* The current location. This is moveable pivot pointing somewhere at - * the middle of @history. */ + /** The current location. This is moveable pivot pointing somewhere at + * 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); diff --git a/src/session/location.c b/src/session/location.c index 2478eb305..408f739d1 100644 --- a/src/session/location.c +++ b/src/session/location.c @@ -1,4 +1,5 @@ -/* Locations handling */ +/** Locations handling + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" diff --git a/src/session/location.h b/src/session/location.h index e135b003b..a3bd537fb 100644 --- a/src/session/location.h +++ b/src/session/location.h @@ -16,7 +16,7 @@ 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! */ void destroy_location(struct location *); #endif diff --git a/src/session/session.c b/src/session/session.c index f60d7d5c0..2f36c5602 100644 --- a/src/session/session.c +++ b/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 @@ -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) @@ -440,7 +441,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) @@ -741,7 +742,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) @@ -821,7 +822,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 @@ -991,7 +992,7 @@ encode_session_info(struct string *info, 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. @@ -1000,12 +1001,11 @@ encode_session_info(struct string *info, * 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) { @@ -1279,9 +1279,9 @@ tabwin_func(struct window *tab, struct term_event *ev) } } -/* - * Gets the url being viewed by this session. Writes it into str. - * A maximum of str_size bytes (including null) will be written. +/** + * Gets the url being viewed by this session. Writes it into @a str. + * A maximum of @a str_size bytes (including null) will be written. */ unsigned char * get_current_url(struct session *ses, unsigned char *str, size_t str_size) @@ -1304,9 +1304,9 @@ 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. - * A maximum of str_size bytes (including null) will be written. +/** + * Gets the title of the page being viewed by this session. Writes it into + * @a str. A maximum of @a str_size bytes (including null) will be written. */ unsigned char * get_current_title(struct session *ses, unsigned char *str, size_t str_size) @@ -1323,9 +1323,9 @@ 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. - * A maximum of str_size bytes (including null) will be written. +/** + * Gets the url of the link currently selected. Writes it into @a str. + * A maximum of @a str_size bytes (including null) will be written. */ unsigned char * get_current_link_url(struct session *ses, unsigned char *str, size_t str_size) @@ -1339,9 +1339,9 @@ 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 - * (the text between and ), str is a preallocated string, - * str_size includes the null char. */ +/** get_current_link_name: returns the name of the current link + * (the text between and ), @a str is a preallocated string, + * @a str_size includes the null char. */ unsigned char * get_current_link_name(struct session *ses, unsigned char *str, size_t str_size) { diff --git a/src/session/session.h b/src/session/session.h index 1aac8827a..eb9544edd 100644 --- a/src/session/session.h +++ b/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 - * intermediately per-session. */ + /** This is the repeat count being inserted by user so far. + * 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 - * action are we supposed to do when we receive the next key. */ + /** If the previous key was a mark prefix, this describes what kind + * 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,17 +133,20 @@ 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 + * @{ */ LIST_OF(struct file_to_load) more_files; @@ -158,31 +161,34 @@ struct session { struct uri *download_uri; - /* The URI which is the referrer to the current loaded document 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 - * at the lower ones. */ + /** The URI which is the referrer to the current loaded document + * or NULL if there are no referrer. + * + * The @c referrer member's sole purpose is to have the information + * 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,30 @@ 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?) */ LIST_OF(struct type_query) type_queries; - /* The info for status displaying */ + /** The info for status displaying */ struct session_status status; + + /** @} */ }; 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. - * That's nice for encapsulation and alrady paid out once ;-). */ +/** This returns a pointer to the current location inside of the given session. + * 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. */ static inline int have_location(struct session *ses) { return !!cur_loc(ses); } -/* Swaps the current session referrer with the new one passed as @referrer */ -/* @referrer may be NULL */ +/** Swaps the current session referrer with the new one passed as @a referrer. + * @a referrer may be NULL. */ void set_session_referrer(struct session *ses, struct uri *referrer); void @@ -224,11 +232,11 @@ void process_file_requests(struct session *); 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 - * sessions. */ +/** @returns zero if the info was remote sessions or if it failed to + * 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); @@ -249,12 +257,12 @@ 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 - * @req_sent into account. */ -struct download *get_current_download(struct session *ses); +/** session_is_loading() is like !!get_current_download() but doesn't take + * session.req_sent into account. */ 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); @@ -269,7 +277,7 @@ 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 diff --git a/src/session/task.c b/src/session/task.c index 14694b02c..d9258354f 100644 --- a/src/session/task.c +++ b/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 - * frameset, and we basically just reset the appropriate frame's view_state in +/** If @a loaded_in_frame is set, this was called just to indicate a move inside + * 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 - * later the file-to-load callback calls it for the particular frame with - * @loaded_in_frame set. */ + * with @a loaded_in_frame unset, duplicating the whole frameset's location, + * then later the file-to-load callback calls it for the particular frame with + * @a loaded_in_frame set. */ struct view_state * ses_forward(struct session *ses, int loaded_in_frame) { diff --git a/src/session/task.h b/src/session/task.h index f61747bbc..08caff60f 100644 --- a/src/session/task.h +++ b/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 - * in-imagemap links. */ +/** This is for map_selected(), it is used to pass around information + * about in-imagemap links. */ struct link_def { unsigned char *link; unsigned char *target;