octave-maintainers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: deftypefn or defun (deffn)


From: JuanPi
Subject: Re: deftypefn or defun (deffn)
Date: Thu, 21 Apr 2016 18:34:50 +0200

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

-- 
JuanPi Carbajal
Public GnuPG key: 9C5B72BF
-----
The end of funding: "Many researchers were caught up in a web of
increasing exaggeration."
- Hans Moravec



reply via email to

[Prev in Thread] Current Thread [Next in Thread]