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;