Re: deftypefn or defun (deffn)

[Oliver Heimlich]

On 21.04.2016 18:34, JuanPi wrote:
> On Thu, Apr 21, 2016 at 6:20 PM, Oliver Heimlich <address@hidden> wrote:
>> 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
> 
> Oliver,
> Thanks.
> How do you do to show output arguments in your functions
> documentation? It doesn't seem you have many that return varargout
> 

I use the @deftype… macros to show output arguments. However, I only do
so if there are more than one or if the output is non-trivial. This also
seems to be the best-practice in Octave core. For example see

http://octave.sourceforge.net/interval/function/@infsup/setxor.html
http://octave.sourceforge.net/interval/function/@infsup/meshgrid.html
http://octave.sourceforge.net/interval/function/@infsup/lu.html
http://octave.sourceforge.net/interval/function/@infsup/fsolve.html