Re: remove function class from docstrings in Octave-Forge

[Oliver Heimlich]

On 13.12.2015 22:00, Carlo De Falco wrote:
> Hi,
> 
> One of the tasks of the 2015 Codesprint 
> was to remove function class from docstrings 
> in Octave-Forge [1,2,3]. 
> 
> If I recall correctly Rik accomplished this
> with a Perl script.
> 
> Rik, I think it would make sense to make such script available
> so tha forge package maintainers can apply similar changes to 
> their packages.
> 
> What do you think?

Due to the extra formatting/postprocessing introduced in [4], the
problem with the packages is that the documentation would look bad in
old versions of Octave, which would have the “ -- : ” in front of every
function declaration. Also we would need a similar change for the html
output from the generate_html package.

Why don't we use standard Texinfo conventions?

@deftypefun (notice the extra “u”) for functions with return values
 -- Function: y = foo (x)

@defun for functions without (named) return values
 -- Function: display (s)

@deffn Command ... for function calls with command syntax
 -- Command: format long

@deftypemethod for class methods with return values
 -- Method of @foo: y = bar (o)

@defmethod for class methods without return values
 -- Method of @foo: display (o)

(You could even add another category for operator syntax.)

These function categories make more sense than the old categories from
the user's perspective, because they indicate how the function can be
called and used (and not how they are implemented).

This also had the benefit that we don't have to workaround some Texinfo
functionality.

Oliver


> [1] http://wiki.octave.org/Remove_class_of_function_from_documentation_strings
> [2] http://hg.savannah.gnu.org/hgweb/octave/rev/516bb87ea72e
> [3] http://hg.savannah.gnu.org/hgweb/octave/rev/1142cf6abc0d

[4] http://hg.savannah.gnu.org/hgweb/octave/rev/5e16d687a701