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

[Xiao-Yong Jin]

The last thing we want is to add one more implementation dependent
feature to an already fractured APL ecosystem.

If our developers prefer a set of strict rules of doxygen style
documents, you can make your own simple documentation list with
awk.  The following one liner should do the trick.  I've been using
a similar one for my bash scripts.

   awk '/^∇[   ]*[a-zA-Z_⍙]+/{def=1}
        def==1&&/^∇[^     ]+|^[   ]*⍝/{print}
        /^[         ]+[^    ⍝]|^∇[  ]*$/{def=0}' \
   "$@" \
   | column -s⍝ -t

Tested on both iso_cf.apl and FILE_IO.apl.
Try it for yourself.  You need a terminal with ⎕PW > 120

> On Apr 18, 2017, at 11:19 AM, Elias Mårtenson <address@hidden> wrote:
> 
> 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