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

[Juergen Sauermann]

Hi David,

I believe the initial question was whether we should adopt the Doxygen style of comments or
the toronto toolkit style.

So this means do we prefer to be locked into Doxygen or into the toronto toolkit?

We could of course adopt a third style so that we are neither locked into Doxygen nor into
the toronto toolkit, but that would make the comments the most useless.

I cannot judge how powerful the comment extracting capabilities of the toronto toolkit
are, but I know that those of Doxygen are quite impressive: caller graphs, call graphs,
varous lists (functions, variables), different output formats (HTML, PDF, TeX, and a few more).

If the toronto toolkit is also capable of all this then fine. Otherwise we should push for Doxygen
support for APL. Right now Doxygen does not have support for APL but it seems quite feasible
to add that if we contribute to the Doxygen project instead of just asking them for supporting APL.

And of course in the end it should be the users that decide which format they prefer (if any).

/// Jürgen

On 04/18/2017 05:57 PM, David B. Lamkins wrote:

On Tue, Apr 18, 2017 at 10:49:28AM +0800, Elias Mårtenson 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.

Is "all the leading comment lines until the first non-comment line" that complex? I'm just trying to be precise about what's a "header comment" and what's not.

Given the double-lamp convention, what's the expected behavior if I drop a double-lamp comment in the middle of my APL code? Is that still part of the header comment?

The problem with adopting a convention from an existing tool is that it locks everyone into using that tool, whether it's their preference to use that tool or not. Because GNU APL can deal with program text stored on a Unicode file, any tool can process that file. I think it's presumptive to declare any particular markup format as "standard". Let the user decide.

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.

What's an "arbitrary" comment? In my proposal, the comments at the top of the function are the header comment. Every comment after the first line of APL code or empty line is not part of the header comment.

The only thing the double-lamp convention does is to let you use grep rather than a simple parsert that can identify the start of a user-defined function and a comment-only line. That's really not difficult. And of course the "grep" approach opens up questions like the one I raised above about "header" comments tucked into the middle of a function.

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.

Let's not conflate the importance of documentation with the syntax of the comments. All I'm arguing for is to not impose a special syntax on "header" comments. A header comment is simply the comments at the top of the function. Period. Doesn't need to be any more complex than that.