This all looks great btw - great addition to system
On Tue, 18 Apr 2017 10:49:28 +0800
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 ⍝⍝
what happens with ⍝⍝ ∇ <snicker>
> 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
> >
> >
