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

[David B. Lamkins]

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.

-- 
Thieves respect property; they merely wish the property to become
their property that they may more perfectly respect it.
                -- G.K. Chesterton, "The Man Who Was Thursday"