[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Cleaning up @deftypefn classes in documentation
From: |
Rik |
Subject: |
Re: Cleaning up @deftypefn classes in documentation |
Date: |
Fri, 12 Jul 2013 11:32:42 -0700 |
On 07/12/2013 10:55 AM, Carnë Draug wrote:
> On 10 July 2013 18:49, Rik <address@hidden> wrote:
>> The Command form would be used only when the function works for all
>> different input combinations in the command form. If there is a single
>> situation where it doesn't then the Function keyword would be used.
> This would mean that a function can only have one type of usage which
> is not true.
Yes. I pointed out earlier that distinction between command and function
isn't absolute since any function can be called in the command form.
Therefore, this was a way of distinguishing between them. See below as well.
> Those values are arguments for deftypefn and deftypefnx
> not to the function. For example, I have recently documented an usage
> of colormap() of the Command style so its help text shows both
> "Function File" and "Command".
You can have both, but I don't like the output it produces in fixed width
environments because columns are no longer aligned. Take for example 'dbstop',
-- Built-in Function: RLINE = dbstop ("FUNC")
-- Built-in Function: RLINE = dbstop ("FUNC", LINE)
-- Built-in Function: RLINE = dbstop ("FUNC", LINE1, LINE2, ...)
which could be written as
-- Command: RLINE = dbstop "FUNC"
-- Built-in Function: RLINE = dbstop ("FUNC", LINE)
-- Built-in Function: RLINE = dbstop ("FUNC", LINE1, LINE2, ...)
but then I find it difficult to see what is changing between one invocation
and the next.
I think the documentation will be too messy if we document that every
function with no arguments can be called in the command form as well as the
function form. I would rather make a subsection of the documentation on
calling conventions where we explain the general rule about using/not-using
parentheses to invoke a function and what it means for the class of the
input argument.
--Rik