[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
documentation style question
From: |
John W. Eaton |
Subject: |
documentation style question |
Date: |
Fri, 12 Sep 2014 11:32:54 -0400 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Icedove/24.5.0 |
I'd like to be consistent in the way we document functions like grid
that have a number of different options.
In older versions of Octave, we had
## @deftypefn {Function File} {} grid (@var{arg})
## @deftypefnx {Function File} {} grid ("minor", @var{arg2})
## @deftypefnx {Function File} {} grid (@var{hax}, @dots{})
## Force the display of a grid on the plot.
## The argument may be either @code{"on"}, or @code{"off"}.
## If it is omitted, the current grid state is toggled.
## ...
so we showed a small number of different forms and explained the valid
values for the arguments.
Now we have
## @deftypefn {Command} {} grid
## @deftypefnx {Command} {} grid on
## @deftypefnx {Command} {} grid off
## @deftypefnx {Command} {} grid minor
## @deftypefnx {Command} {} grid minor on
## @deftypefnx {Command} {} grid minor off
## @deftypefnx {Function File} {} grid (@var{hax}, @dots{})
## Control the display of plot grid lines.
##
## The function state input may be either @qcode{"on"} or @qcode{"off"}.
## If it is omitted, the current grid state is toggled.
so we are enumerating all the options. The following description no
longer seems to apply (what input state?) so it seems like it should be
edited.
Do people prefer the current way of listing all the possibilities? I'm
working on adding the zoom function and if documented this way, there
will be 10 lines enumerating the different ways it can be called.
Also, why distinguish between Command and Function File now that any
function that accepts character string arguments can be called with
"command" syntax?
jwe
- documentation style question,
John W. Eaton <=