Browse Source

Use @retval in codedocs

master^2
Benedikt Heine 3 years ago
parent
commit
16fcbc9db9
  1. 2
      HACKING.md
  2. 3
      src/dbus.c
  3. 14
      src/icon.h
  4. 3
      src/markup.c
  5. 1
      src/menu.h
  6. 11
      src/queues.c
  7. 11
      src/queues.h
  8. 6
      src/x11/screen.h

2
HACKING.md

@ -6,6 +6,8 @@
- Comment system is held similar to JavaDoc
- Use `@param` to describe all input parameters
- Use `@return` to describe the output value
- Use `@retval` to describe special return values (like `NULL`)
- Documentation comments should start with a double star (`/**`)
- Append `()` to function names and prepend variables with `#` to properly reference them in the docs
- Add comments to all functions and methods

3
src/dbus.c

@ -461,7 +461,8 @@ static void dbus_cb_name_acquired(GDBusConnection *connection,
* @param name The place to report the name to, if not required set to NULL
* @param vendor The place to report the vendor to, if not required set to NULL
*
* @returns `true` on success, otherwise `false`
* @retval true: on success
* @retval false: Any error happened
*/
static bool dbus_get_fdn_daemon_info(GDBusConnection *connection,
guint *pid,

14
src/icon.h

@ -23,7 +23,8 @@ GdkPixbuf *icon_pixbuf_scale(GdkPixbuf *pixbuf);
*
* @param filename A string representing a readable file path
*
* @return an instance of `GdkPixbuf` or `NULL` if file does not exist
* @return an instance of `GdkPixbuf`
* @retval NULL: file does not exist, not readable, etc..
*/
GdkPixbuf *get_pixbuf_from_file(const char *filename);
@ -33,7 +34,8 @@ GdkPixbuf *get_pixbuf_from_file(const char *filename);
* or an icon name, which then gets searched for in the
* settings.icon_path
*
* @return an instance of `GdkPixbuf` or `NULL` if not found
* @return an instance of `GdkPixbuf`
* @retval NULL: file does not exist, not readable, etc..
*/
GdkPixbuf *get_pixbuf_from_icon(const char *iconname);
@ -47,8 +49,8 @@ GdkPixbuf *get_pixbuf_from_icon(const char *iconname);
* get searched in the folders of the icon_path setting.
* @param id (necessary) A unique identifier of the returned pixbuf. Only filled,
* if the return value is non-NULL.
* @return a pixbuf representing name's image.
* If an invalid path given, it will return NULL.
* @return an instance of `GdkPixbuf`, representing the name's image
* @retval NULL: Invalid path given
*/
GdkPixbuf *icon_get_for_name(const char *name, char **id);
@ -61,8 +63,8 @@ GdkPixbuf *icon_get_for_name(const char *name, char **id);
* like described in the notification spec.
* @param id (necessary) A unique identifier of the returned pixbuf.
* Only filled, if the return value is non-NULL.
* @return a pixbuf representing name's image.
* If an invalid GVariant is passed, it will return NULL.
* @return an instance of `GdkPixbuf` derived from the GVariant
* @retval NULL: GVariant parameter nulled, invalid or in wrong format
*/
GdkPixbuf *icon_get_for_data(GVariant *data, char **id);

3
src/markup.c

@ -236,7 +236,8 @@ char *markup_strip(char *str)
* Determine if an & character pointed to by \p str is a markup & entity or
* part of the text
*
* @return true if it's an entity otherwise false
* @retval true: \p str is an entity
* @retval false: It's no valid entity
*/
static bool markup_is_entity(const char *str)
{

1
src/menu.h

@ -7,6 +7,7 @@
*
* @param to_match (nullable) String to extract URLs
* @return a string of urls separated by '\n'
* @retval NULL: No URLs found
*/
char *extract_urls(const char *to_match);

11
src/queues.c

@ -127,7 +127,8 @@ static bool queues_notification_is_ready(const struct notification *n, struct du
*
* @param n the notification to check
* @param status the current status of dunst
* @returns true, if the notification is timed out, otherwise false
* @retval true: the notification is timed out
* @retval false: otherwise
*/
static bool queues_notification_is_finished(struct notification *n, struct dunst_status status)
{
@ -206,8 +207,8 @@ int queues_notification_insert(struct notification *n)
/**
* Replaces duplicate notification and stacks it
*
* @return true, if notification got stacked
* @return false, if notification did not get stacked
* @retval true: notification got stacked
* @retval false: notification did not get stacked
*/
static bool queues_stack_duplicate(struct notification *n)
{
@ -245,8 +246,8 @@ static bool queues_stack_duplicate(struct notification *n)
/**
* Replaces the first notification of the same stack_tag
*
* @return true, if notification got stacked
* @return false, if notification did not get stacked
* @retval true: notification got stacked
* @retval false: notification did not get stacked
*/
static bool queues_stack_by_tag(struct notification *new)
{

11
src/queues.h

@ -29,7 +29,8 @@ const GList *queues_get_displayed(void);
/**
* Get the highest notification in line
*
* @return a notification or NULL, if waiting is empty
* @returns the first notification in waiting
* @retval NULL: waiting is empty
*/
const struct notification *queues_get_head_waiting(void);
@ -61,8 +62,8 @@ unsigned int queues_length_history(void);
* - If n->id != 0, n replaces notification n with id n->id
* - If n->id == 0, n gets a new id assigned
*
* @return `0`, the notification was dismissed and freed
* @return The new value of `n->id`
* @returns The new value of `n->id`
* @retval 0: the notification was dismissed and freed
*/
int queues_notification_insert(struct notification *n);
@ -73,8 +74,8 @@ int queues_notification_insert(struct notification *n);
*
* @param new replacement for the old notification
*
* @return true, if a matching notification has been found and is replaced
* @return false, else
* @retval true: a matching notification has been found and is replaced
* @retval false: otherwise
*/
bool queues_notification_replace_id(struct notification *new);

6
src/x11/screen.h

@ -29,7 +29,8 @@ double get_dpi_for_screen(struct screen_info *scr);
* @see window_is_fullscreen()
* @see get_focused_window()
*
* @return `true` if the focused window is in fullscreen mode
* @retval true: the focused window is in fullscreen mode
* @retval false: otherwise
*/
bool have_fullscreen_window(void);
@ -37,7 +38,8 @@ bool have_fullscreen_window(void);
* Check if window is in fullscreen mode
*
* @param window the x11 window object
* @return `true` if `window` is in fullscreen mode
* @retval true: \p window is in fullscreen mode
* @retval false: otherwise
*/
bool window_is_fullscreen(Window window);

Loading…
Cancel
Save