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 <loke...@gmail.com> wrote: > > On 18 April 2017 at 23:57, David B. Lamkins <da...@lamkins.net> 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