From: Andrew Burgess <aburgess@redhat.com>
Date: Wed, 23 Apr 2025 08:48:11 +0000 (+0100)
Subject: gdb/doc: tweaks to documentation for gdb.Color
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=94f3facb2185f780b9b971330277c6d89ad8c053;p=thirdparty%2Fbinutils-gdb.git

gdb/doc: tweaks to documentation for gdb.Color

While reading through the documentation for the new gdb.Color class I
spotted a couple of things which I thought could be improved:

  * I replaced @code{Color} with @code{gdb.Color}.  Most of the other
    classes are referenced with the 'gdb.' prefix, so this makes
    gdb.Color consistent.  Including the 'gdb.' prefix makes it far
    easier to search the documentation to find relevant content.  And
    finally, my understanding is that usually in Python code, the
    class would be written as 'gdb.Color' unless the user specifically
    pulls 'Color' into the current scope using 'from gdb import
    Color'.

  * Replace 'colorspace' with 'color space'.  There was already a use
    of the two word form in the documentation (for gdb.Color), so this
    just makes things consistent.

  * Removed use of @var on two @defun lines.  No other @defun lines
    use @var, so the use of @var here was making the output
    inconsistent, e.g. in the 'info' output, @var causes the string to
    be capitalised.

  * Rename the 'color-space' argument to 'color_space' for
    Color.__init__.  In the next commit I plan to add Python keyword
    argument support to this function, which means the argument name
    needs to be a valid keyword (i.e. must not contain the '-'
    character).

  * Added a pointer to where the @samp{COLORSPACE_} constants can be
    found.  These constants are referenced before they are defined in
    the documentation, which is fine, but I think it is a good idea to
    let the user know where the constants can be found when we first
    reference them.

  * Remove use of 'self' for the Color.escape_sequence documentation.
    There are a few functions that do include 'self' as an argument (I
    think this is a mistake) but the vast majority don't.  I think not
    including 'self' is the better approach; a user wouldn't be
    expected to explicitly pass 'self', this is done automatically by
    Python as a result of calling the method on an object.  So I've
    removed the reference to 'self' from this method.

Approved-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
---

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 45f5f70e4ad..cba3a0d2fa5 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -7049,13 +7049,13 @@ writable.
 
 @cindex colors in python
 @tindex gdb.Color
-You can assign instance of @code{Color} to the @code{value} of
+You can assign instance of @code{gdb.Color} to the @code{value} of
 a @code{Parameter} instance created with @code{PARAM_COLOR}.
 
-@code{Color} may refer to an index from color palette or contain components
-of a color from some colorspace.
+@code{gdb.Color} may refer to an index from a color palette or contain
+components of a color from some color space.
 
-@defun Color.__init__ (@r{[}@var{value} @r{[}, @var{color-space}@r{]}@r{]})
+@defun Color.__init__ (@r{[}value @r{[}, color_space@r{]}@r{]})
 
 @var{value} is @code{None} (meaning the terminal's default color),
 an integer index of a color in palette, tuple with color components
@@ -7065,8 +7065,9 @@ or one of the following color names:
 @samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan},
 or @samp{white}.
 
-@var{color-space} should be one of the @samp{COLORSPACE_} constants.  This
-argument tells @value{GDBN} which color space @var{value} belongs.
+@var{color_space} should be one of the @samp{COLORSPACE_} constants
+listed below.  This argument tells @value{GDBN} which color space
+@var{value} belongs.
 @end defun
 
 @defvar Color.is_none
@@ -7094,7 +7095,7 @@ This attribute exist if @code{is_direct} is @code{True}.  Its value is tuple
 with integer components of a color.
 @end defvar
 
-@defun Color.escape_sequence (@var{self}, @var{is_foreground})
+@defun Color.escape_sequence (is_foreground)
 Returns string to change terminal's color to this.
 
 If @var{is_foreground} is @code{True}, then the returned sequence will change