From e7b4380d785ef641583171caabf4eef9cdff07c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Andr=C3=A9=20Tanner?= Date: Wed, 29 Jul 2020 11:13:53 +0200 Subject: doc: fix a couple of API doc warnings In restructured text double backquotes are used for inline literals. --- buffer.h | 2 +- doc/text.rst | 6 +++--- text.h | 32 ++++++++++++++++---------------- view.h | 16 ++++++++-------- 4 files changed, 28 insertions(+), 28 deletions(-) diff --git a/buffer.h b/buffer.h index a041e5e..52f1cb4 100644 --- a/buffer.h +++ b/buffer.h @@ -75,7 +75,7 @@ const char *buffer_content(Buffer*); /** * Borrow underlying buffer data. * @rst - * .. warning:: The caller is responsible to `free(3)` it. + * .. warning:: The caller is responsible to ``free(3)`` it. * @endrst */ char *buffer_move(Buffer*); diff --git a/doc/text.rst b/doc/text.rst index 767bf29..8bbef5b 100644 --- a/doc/text.rst +++ b/doc/text.rst @@ -4,7 +4,7 @@ Text The core text management data structure which supports efficient modifications and provides a byte string interface. Text positions are represented as ``size_t``. Valid addresses are in range ``[0, -text_size(txt)]``. An invalid position is denoted by `EPOS`. Access to +text_size(txt)]``. An invalid position is denoted by ``EPOS``. Access to the non-contigiuos pieces is available by means of an iterator interface or a copy mechanism. Text revisions are tracked in an history graph. @@ -77,7 +77,7 @@ These functions advance to the next/previous grapheme cluster. .. note:: The grapheme cluster boundaries are currently not implemented according to `UAX#29 rules `_. Instead a base character followed by arbitrarily many combining - character as reported by `wcwidth(3)` are skipped. + character as reported by ``wcwidth(3)`` are skipped. .. doxygengroup:: iterator_char :content-only: @@ -105,7 +105,7 @@ A mark keeps track of a text position. Subsequent text changes will update all marks placed after the modification point. Reverting to an older text state will hide all affected marks, redoing the changes will restore them. -.. warning:: Due to an optimization cached modifications (i.e. no `text_snaphot` +.. warning:: Due to an optimization cached modifications (i.e. no ``text_snaphot`` was performed between setting the mark and issuing the changes) might not adjust mark positions accurately. diff --git a/text.h b/text.h index 5d653ff..64795ee 100644 --- a/text.h +++ b/text.h @@ -12,7 +12,7 @@ /** A mark. */ typedef uintptr_t Mark; -/** An invalid mark, lookup of which will yield `EPOS`. */ +/** An invalid mark, lookup of which will yield ``EPOS``. */ #define EMARK ((Mark)0) /** An invalid position. */ #define EPOS ((size_t)-1) @@ -221,7 +221,7 @@ size_t text_lineno_by_pos(Text*, size_t pos); */ bool text_byte_get(Text*, size_t pos, char *byte); /** - * Store at most `len` bytes starting from ``pos`` into ``buf``. + * Store at most ``len`` bytes starting from ``pos`` into ``buf``. * @param pos The absolute starting position. * @param len The length in bytes. * @param buf The destination buffer. @@ -238,7 +238,7 @@ size_t text_bytes_get(Text*, size_t pos, size_t len, char *buf); * @return A contigious NUL terminated buffer holding the requested range, or * ``NULL`` in error case. * @rst - * .. warning:: The returned pointer must be `free(3)`-ed by the caller. + * .. warning:: The returned pointer must be freed by the caller. * @endrst */ char *text_bytes_alloc0(Text*, size_t pos, size_t len); @@ -283,17 +283,17 @@ bool text_iterator_char_prev(Iterator*, char *c); /** * Set a mark. * @rst - * .. note:: Setting a mark to `text_size` will always return the current text - * size upon lookup. + * .. note:: Setting a mark to ``text_size`` will always return the + * current text size upon lookup. * @endrst * @param pos The position at which to store the mark. - * @return The mark or `EMARK` if an invalid position was given. + * @return The mark or ``EMARK`` if an invalid position was given. */ Mark text_mark_set(Text*, size_t pos); /** * Lookup a mark. * @param mark The mark to look up. - * @return The byte position or `EPOS` for an invalid mark. + * @return The byte position or ``EPOS`` for an invalid mark. */ size_t text_mark_get(Text*, Mark); /** @@ -308,12 +308,12 @@ enum TextSaveMethod { /** Automatically chose best option. */ TEXT_SAVE_AUTO, /** - * Save file atomically using `rename(2)`. + * Save file atomically using ``rename(2)``. * * Creates a temporary file, restores all important meta data, * before moving it atomically to its final (possibly already - * existing) destination using `rename(2)`. For new files, - * permissions are set to `0666 & ~umask`. + * existing) destination using ``rename(2)``. For new files, + * permissions are set to ``0666 & ~umask``. * * @rst * .. warning:: This approach does not work if: @@ -353,12 +353,12 @@ bool text_save_method(Text*, const char *filename, enum TextSaveMethod); /** * Setup a sequence of write operations. * - * The returned `TextSave` pointer can be used to write multiple, possibly + * The returned ``TextSave`` pointer can be used to write multiple, possibly * non-contigious, file ranges. * @rst - * .. warning:: For every call to `text_save_begin` there must be exactly - * one matching call to either `text_save_commit` or - * `text_save_cancel` to release the underlying resources. + * .. warning:: For every call to ``text_save_begin`` there must be exactly + * one matching call to either ``text_save_commit`` or + * ``text_save_cancel`` to release the underlying resources. * @endrst */ TextSave *text_save_begin(Text*, const char *filename, enum TextSaveMethod); @@ -371,7 +371,7 @@ ssize_t text_save_write_range(TextSave*, Filerange*); * Commit changes to disk. * @return Whether changes have been saved. * @rst - * .. note:: Releases the underlying resources and `free(3)`'s the given `TextSave` + * .. note:: Releases the underlying resources and frees the given ``TextSave`` * pointer which must no longer be used. * @endrst */ @@ -381,7 +381,7 @@ bool text_save_commit(TextSave*); * @rst * .. note:: Does not guarantee to undo the previous writes (they might have been * performed in-place). However, it releases the underlying resources and - * `free(3)`'s the given `TextSave` pointer which must no longer be used. + * frees the given ``TextSave`` pointer which must no longer be used. * @endrst */ void text_save_cancel(TextSave*); diff --git a/view.h b/view.h index 4d01564..e30946e 100644 --- a/view.h +++ b/view.h @@ -56,13 +56,13 @@ Filerange view_viewport_get(View*); /** * Get window coordinate of text position. * @param pos The position to query. - * @param line Will be updated with screen line on which `pos` resides. - * @param row Will be updaded with zero based window row on which `pos` resides. - * @param col Will be updated with zero based window column which `pos` resides. - * @return Whether `pos` is visible. If not, the pointer arguments are left unmodified. + * @param line Will be updated with screen line on which ``pos`` resides. + * @param row Will be updaded with zero based window row on which ``pos`` resides. + * @param col Will be updated with zero based window column which ``pos`` resides. + * @return Whether ``pos`` is visible. If not, the pointer arguments are left unmodified. */ bool view_coord_get(View*, size_t pos, Line **line, int *row, int *col); -/** Get position at the start ot the `n`-th window line, counting from 1. */ +/** Get position at the start ot the ``n``-th window line, counting from 1. */ size_t view_screenline_goto(View*, int n); /** Get first screen line. */ Line *view_lines_first(View*); @@ -147,7 +147,7 @@ void view_selections_dispose_all(View*); void view_selections_normalize(View*); /** * Replace currently active selections. - * @param array The Array of ``Filerange``s. + * @param array The array of ``Filerange`` objects. * @param anchored Whether *all* selection should be anchored. */ void view_selections_set_all(View*, Array*, bool anchored); @@ -176,7 +176,7 @@ int view_selections_count(View*); /** * Get selection index. * @rst - * .. note:: Is always in range `[0, count-1]`. + * .. note:: Is always in range ``[0, count-1]``. * .. warning: The relative order is determined during creation and assumed * to remain the same. * @endrst @@ -259,7 +259,7 @@ Line *view_cursors_line_get(Selection*); /** * Get zero based index of screen cell on which selection cursor currently resides. * @rst - * .. warning:: Returns `-1` if the selection cursor is currently not visible. + * .. warning:: Returns ``-1`` if the selection cursor is currently not visible. * @endrst */ int view_cursors_cell_get(Selection*); -- cgit v1.2.3