Re: [Bug-apl] Formal format for function documentation

[Kacper Gutowski]

On 2014-07-14 00:01:13, Elias Mårtenson wrote:
> Most modern (and some not-so-modern) languages have a standard way of 
> attaching
> documentation to functions and other symbols.
(...)


I think the most natural way to describe a function is simply by
starting function *body* with a comment:

∇ Z←add1 X
 ⍝ Add one to the right-hand argument.
  Z←X+1
∇

I can't point to any examples right now, but I think I saw this
style being used somewhere before.

Unlike using a comment *before* definition (Javadoc style), comment
inside is actually a part of a function and can be easily extracted
from ⎕CR if needed.  Something like:

  ⊃(1,∧\'⍝'=↑¨1↓C)/C←⊂[⎕IO+1]⎕CR'add1'

I think that assumption that first comment *on the start of line*
documents a function is good enough, but you could also require
additional marker like in Javadoc (perhaps '⍝⍝'?) if you like.

Using a string makes a lot of sense in Lisp because you can manipulate
function's definition directly (code is data).  In APL you have no such
advantage, you need to parse it out yourself anyway, and you have to
additionally supersede its printing using right/left tack or assignment.
To me, this seems pointless and more complicated.

Except, of course, for dfns where you can't write a comment.
But given that dfns in GNU APL can only have single statement, I don't
think that's a big problem as you probably wouldn't write any functions
that need to be documented as dfns.

Using discarded string in dnfs would only result in unnecessarily long
lines which, I think, would only make things harder to read, thus worse.


-k