Re: deftypefn or defun (deffn)

[JuanPi]

On Thu, Apr 21, 2016 at 6:39 PM, Oliver Heimlich <address@hidden> wrote:
> 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
>

Ok, this sounds like a working procedure to me. If outputs are
relevant deftypefn with empty category otherwise use deffn.


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