Re: documentation style question

[Philip Nienhuis]

John W. Eaton wrote
> 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.

As to on-screen help (help <function>): the more compact the better.  10
lines showing how a function can be called looks like overkill.

But the help text is also used to construct the manual / on-line
documentation, and I suppose users wouldn't mind, or might want/expect, some
more detail there (I would).

Philip




--
View this message in context: 
http://octave.1599824.n4.nabble.com/documentation-style-question-tp4666475p4666478.html
Sent from the Octave - Maintainers mailing list archive at Nabble.com.