Re: [Bug-apl] )HELP ...

[Juergen Sauermann]

Hi,

as some of you may have noticed in the GNU APL source code, I am a big fan of Doxygen.
The ⍝⍝ idea adopts the practice of Doxygen to repeat the last character of comment markers
in a language (Doxyge supports several languages today, but not (yet) APL).

In C we have short (1-line)  // comments and long (1 or more line)  /* .. */ comments. The corresponding
Doxygen comments are therefore /// (short) and /** ... */ (long).

Since APL has no multiline comments we have only ⍝ and then ⍝⍝ would be the corresponging Doxyhen marker.

If course we can make the )HELP mechanism tolerant to support different markers at the same time. But the rules
should be understoof and fixed before I start with the implementation.

What I don't like is when the start marker is the same as the end marker, because it introduces useless error
cases (like missing end marker).

I would also argue that we should separate two things:
(1) the distinction between code extraction comments and normal comments, and
(2) the tagging inside a code extraction comment.

(1) should follow the language (i.e. APL) rules while (2) follows the code extraction rules.

Following that would make:

⍝ Begin a transaction.

a normal comment.

BTW for those of you looking for coding tasks, contributing APL support to Doxygen would
be a useful thing to do. I felt like doing that myself, but I haven't found the time to do it yet.

Best Regards,
Jürgen Sauermann


Which would make . a start/end marker.

On 04/18/2017 04:56 AM, Elias Mårtenson wrote:

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 <address@hidden> 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 <address@hidden> 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