Sorry for following up to my own email, but I forgot to mention one thing:
I have absolutely no particular attachment to the choice of using ⍝⍝. I'm
OK with any format, but the important part is that it's clearly distinct
from any normally occurring comments or code.
If I remember correctly, this was discussed several years ago and one of
the proposals was to use ⍝-, like this:
∇Z←SQL∆Begin db
⍝-
⍝ Begin a transaction.
⍝-
⍝ This is a normal comment that is not part of the documentation.
Z←⎕SQL[5] db
∇
I personally find the ⍝⍝ format to be more readable though, but that's just
my personal taste.
Regards,
Elias
On 18 April 2017 at 10:49, Elias Mårtenson <loke...@gmail.com> wrote:
> Hello David,
>
> Having a standardised format is what makes this so useful. The whole point
> of this is to make sure that everybody uses the same convention so
> third-party tools can integrate with the system. If everybody “adopts the
> convention they prefer”, as you suggest, such a system would not be very
> useful. With regards to the format, I think you are exaggerating the
> complexity a bit. It's really only two rules:
>
> 1. The documentation block is prefixed by ⍝⍝
> 2. The first line is the short summary.
>
> Using a special format to describe documentation is very important. The
> reason is that *you absolutely don't want to display “normal” comments as
> documentation*. Using ⍝⍝ tells the system that the person who wrote the
> documentation intended this to be documentation, and not just merely a
> plain comment.
>
> The Emacs mode dynamically pops up this documentation string whenever the
> cursor is on top of a function name, and you really don't want arbitrary
> comments to be displayed there.
>
> This system of having dedicated documentation strings is very well
> established in multiple languages, for example:
>
> - Java (uses /**)
> - C++ (doxygen, uses /**)
> - Python (uses triple-quote """like this""". An empty string
> conveniently is a no-op in Python)
> - Common Lisp ("a plain string" as the first form, like Python this
> ends up being a no-op)
> - Emacs Lisp (same syntax as Common Lisp, the documentation is tightly
> integrated in the help system)
>
> As you can see, this is nothing new, and has proven to be incredibly
> useful in multiple languages.
>
> Finally, this is not merely a good idea. It's also actively working in the
> GNU APL Emacs mode today, and if you want to have integrated documentation
> in the editor you need to follow this convention anyway.
>
> Regards,
> Elias
>
> On 18 April 2017 at 09:05, David B. Lamkins <da...@lamkins.net> wrote:
>
>> Thank you to everyone who contributed to the recent extension to )HELP.
>> This'll be far more convenient that flipping between APL and two PDF
>> references.
>>
>> Regarding help for user-defined functions, I'd like to offer a suggestion:
>>
>> I've noticed quite a bit of talk about adopting syntax and/or semantics
>> (e.g. tags) from the conventions used by other languages and documentation
>> extractors.
>>
>> I'd like to suggest that it's in everyone's interest for the format of
>> header comments to remain as neutral as possible, leaving open the
>> possibility for everyone to adopt (or invent) whatever convention they
>> prefer.
>>
>> The way I see it, the only real concern should be how to delimit the end
>> of a header comment. I'd like to suggest that every lamp line starting with
>> the first line of the function is a header comment regardless of
>> indentation or markup. The end of the header comment is simply the first
>> non-lamp line; this could be either a line of APL code or an empty line
>> (and I prefer visual equivalence, so a line of only whitespace would be
>> considered empty for this purpose). If the first line of the function is
>> visually empty or a line of APL code, then the function has no header
>> comment.
>>
>> Again, thanks!
>>
>> David
>>
>> --
>> I've found my niche. If you're wondering why I'm not there, there was
>> this little hole in the bottom ...
>> -- John Croll
>>
>>
>
