Re: deftypefn or defun (deffn)

[Oliver Heimlich]

On 21.04.2016 16:35, John W. Eaton wrote:
> On 04/21/2016 10:25 AM, JuanPi wrote:
>> Hi all,
>>
>> Working with a documentation for  anew package I found that we use
>> deftypefn for m-files although functions in Octave are not typed
>> functions. Shouldn't we use defun (a.k.a. deffn) instead? That seem to
>> be the case for the Interval package, but maybe there is a reason tu
>> use the typed function command instead.
> 
> We use deftypefn so that we can show the name of the returned value(s).
>  In places where that is not needed, I suppose we could use deffn.  But
> it seems simpler to me to always use the same form.
> 
> jwe

True, the @deftypefn macro is the most flexible Texinfo macro for
functions, which accepts all of the following parameters: 1. category,
2. data-type, 3. name, 4. arguments.

The @deffn is just a shortcut where data-type would be empty.

On the default branch of Octave we use:
1. category must be {}, see below
2. data-type is the list of return values if present, e. g. {[A, B] =}
3. name is the name of the function, e. g. {f} (is typeset in bold face)
4. arguments is the list of parameters, e. g. {(a, b, @dots{})}

Regarding the category it has been decided to drop that information,
since it contained only the values “Function File” or “Built-in
Function” in the past, which are not very useful.

In the interval package I have chosen to stick to the Texinfo
conventions and use the following categories, depending on the primary
usage of a particular function (it is also possible to mix these
categories with further @def...x macros):
1. Method (see also @defmethod) if the function is used on objects
        e. g. sin (infsup (0))
2. Constructor for class constructors
        e. g. infsup (0)
3. Function (see also @deffun) if the function is used as such
        e. g. empty ()
4. Command if the function is mainly used in command syntax
        e. g. pkg load interval
5. Operator (see also @defop) if it is used in operator syntax
        e. g. a .* b

I strongly disagree with the empty category that is used in Octave core
documentation. It makes the text documentation look ugly with “-- :” at
the beginning of each definition line.

The counter-argument for my reasoning has been that you can use many
functions in both command syntax and function syntax. IMHO it is
sufficient to document the primary usage. In corner cases you may still
document both, see [1] for an example.

Oliver

[1] http://octave.sourceforge.net/interval/function/@infsup/mtimes.html