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>
1 file changed
