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

[Elias Mårtenson]

On 18 April 2017 at 23:57, David B. Lamkins <address@hidden> wrote:

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.

This special comment describes what the function does, in a format suitable to be the reference documentation for the function.

 

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?

No. Although it could be, but then it would probably document a part of the function. That's never part of the API so it doesn't make sense though.

 

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 user can decide. This doesn't change the behaviour of the language at all. A comment is still a comment. The only difference is that you as a programmer makes an explicit decision to tell the tooling that you have written “nice” reference documentation for the function.

If you don't want the tooling to be able to display documentation for your functions, you are perfectly free to completely ignore this convention and everything will work exactly the way you expect it to.

 

> 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.

In this context, an arbitrary comment is a comment which is not part of the formal documentation for the function.

 

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.

No, it doesn't. It does much more than that. It's a signal to the tools that this comment isn't just a comment. It's actually proper API documentation for the function. This is really good, because I definitely don't want my editor to pop up live documentation for a function like this:

∇Z←foo X
⍝ Hmm, 1+x was a bad idea, let's ignore this line for the moment
⍝ Z←1+X
  Z←2+X
∇

When I see this, I assume that the developer who wrote this code did not want to write formal documentation for this function, which is perfectly fine. With your proposal, Emacs would pop up the text: “Hmm, 1+x was a bad idea, let's ignore this line for the moment”, for this function. Nobody wants that, and with the double lamp, nothing is displayed.

I honestly don't understand why you have an issue with this. It literally doesn't change anything at all, unless you like to write formal documentation that is displayed in the developer tools.

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.

Yes, it does have to. The docstrings are not only for the person reading the code, but for automated tools so that they can figure out what is formal documentation, and what is just comments aimed at users who read the code.

Remember, the docstrings are displayed when people use a function, not when they look at the function's code. The whole idea is to streamline the developer workflow so that relevant documentation is displayed in real-time while you write code that uses a function. Perhaps this is the part you are not aware of. Most modern development tools support this, and there is no reason APL can have it too. In fact, Emacs with the APL mode has had it for several years since I wrote the code to handle it.

This code uses this documentation convention right now, and it works great. If you want to propose something different, it needs to be something that is at least as good as what we have today. Your proposal of simply using a single lamp is not that, since it's unable to make a distinction between documentation and “just a comment” at the beginning of a function.

Regards,

Elias