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
