1
0
mirror of https://github.com/rkd77/elinks.git synced 2024-10-01 03:36:26 -04:00

Doxygenate src/session/

This commit is contained in:
Kalle Olavi Niemitalo 2007-07-27 03:07:39 +03:00 committed by Witold Filipczyk
parent 646e6b5c49
commit 012674d8eb
10 changed files with 109 additions and 95 deletions

View File

@ -1,4 +1,5 @@
/* Downloads managment */
/** Downloads managment
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -1049,7 +1050,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)
@ -1062,9 +1063,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)
{

View File

@ -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

View File

@ -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)
{

View File

@ -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);

View File

@ -1,4 +1,5 @@
/* Locations handling */
/** Locations handling
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"

View File

@ -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

View File

@ -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"
@ -65,7 +66,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
@ -140,7 +141,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)
@ -441,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)
@ -742,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)
@ -822,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
@ -992,7 +993,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.
@ -1001,12 +1002,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)
{
@ -1293,9 +1293,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)
@ -1318,9 +1318,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)
@ -1337,9 +1337,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)
@ -1353,9 +1353,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 <A> and </A>), 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 <A> and </A>), @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)
{

View File

@ -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

View File

@ -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)
{

View File

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