[Bug-apl] )HELP ...

[David B. Lamkins]

Thank you to everyone who contributed to the recent extension to )HELP. This'll be far more convenient that flipping between APL and two PDF references.

Regarding help for user-defined functions, I'd like to offer a suggestion:

I've noticed quite a bit of talk about adopting syntax and/or semantics (e.g. tags) from the conventions used by other languages and documentation extractors.

I'd like to suggest that it's in everyone's interest for the format of header comments to remain as neutral as possible, leaving open the possibility for everyone to adopt (or invent) whatever convention they prefer.

The way I see it, the only real concern should be how to delimit the end of a header comment. I'd like to suggest that every lamp line starting with the first line of the function is a header comment regardless of indentation or markup. The end of the header comment is simply the first non-lamp line; this could be either a line of APL code or an empty line (and I prefer visual equivalence, so a line of only whitespace would be considered empty for this purpose). If the first line of the function is visually empty or a line of APL code, then the function has no header comment.

Again, thanks!

David

[Elias Mårtenson]

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.

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.

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.

Finally, this is not merely a good idea. It's also actively working in the
GNU APL Emacs mode today, and if you want to have integrated documentation
in the editor you need to follow this convention anyway.

Regards,
Elias

Post by David B. Lamkins
Thank you to everyone who contributed to the recent extension to )HELP.
This'll be far more convenient that flipping between APL and two PDF
references.
I've noticed quite a bit of talk about adopting syntax and/or semantics
(e.g. tags) from the conventions used by other languages and documentation
extractors.
I'd like to suggest that it's in everyone's interest for the format of
header comments to remain as neutral as possible, leaving open the
possibility for everyone to adopt (or invent) whatever convention they
prefer.
The way I see it, the only real concern should be how to delimit the end
of a header comment. I'd like to suggest that every lamp line starting with
the first line of the function is a header comment regardless of
indentation or markup. The end of the header comment is simply the first
non-lamp line; this could be either a line of APL code or an empty line
(and I prefer visual equivalence, so a line of only whitespace would be
considered empty for this purpose). If the first line of the function is
visually empty or a line of APL code, then the function has no header
comment.
Again, thanks!
David
--
I've found my niche. If you're wondering why I'm not there, there was
this little hole in the bottom ...
-- John Croll

[Elias Mårtenson]

Sorry for following up to my own email, but I forgot to mention one thing:

I have absolutely no particular attachment to the choice of using ⍝⍝. I'm
OK with any format, but the important part is that it's clearly distinct
from any normally occurring comments or code.

If I remember correctly, this was discussed several years ago and one of
the proposals was to use ⍝-, like this:

∇Z←SQL∆Begin db
⍝-
⍝ Begin a transaction.
⍝-
⍝ This is a normal comment that is not part of the documentation.
Z←⎕SQL[5] db
∇

I personally find the ⍝⍝ format to be more readable though, but that's just
my personal taste.

Regards,
Elias

Post by Elias MÃ¥rtenson
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
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.
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.
This system of having dedicated documentation strings is very well
- 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.
Finally, this is not merely a good idea. It's also actively working in the
GNU APL Emacs mode today, and if you want to have integrated documentation
in the editor you need to follow this convention anyway.
Regards,
Elias

Post by David B. Lamkins
Thank you to everyone who contributed to the recent extension to )HELP.
This'll be far more convenient that flipping between APL and two PDF
references.
I've noticed quite a bit of talk about adopting syntax and/or semantics
(e.g. tags) from the conventions used by other languages and documentation
extractors.
I'd like to suggest that it's in everyone's interest for the format of
header comments to remain as neutral as possible, leaving open the
possibility for everyone to adopt (or invent) whatever convention they
prefer.
The way I see it, the only real concern should be how to delimit the end
of a header comment. I'd like to suggest that every lamp line starting with
the first line of the function is a header comment regardless of
indentation or markup. The end of the header comment is simply the first
non-lamp line; this could be either a line of APL code or an empty line
(and I prefer visual equivalence, so a line of only whitespace would be
considered empty for this purpose). If the first line of the function is
visually empty or a line of APL code, then the function has no header
comment.
Again, thanks!
David
--
I've found my niche. If you're wondering why I'm not there, there was
this little hole in the bottom ...
-- John Croll

[Juergen Sauermann]

<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<font face="Helvetica, Arial, sans-serif">Hi,<br>
<br>
as some of you may have noticed in the GNU APL source code, I am a
big fan of Doxygen.<br>
The ⍝⍝ idea adopts the practice of Doxygen to repeat the last
character of comment markers<br>
in a language (Doxyge supports several languages today, but not
(yet) APL).<br>
<br>
In C we have short (1-line)  <font face="Courier New, Courier,
monospace"><b>//</b></font> comments and long (1 or more line) 
<b><font face="Courier New, Courier, monospace">/* .. *</font>/ </b>comments.
The corresponding<br>
Doxygen comments are therefore <font face="Courier New, Courier,
monospace"><b>///</b></font> (short) and <font face="Courier
New, Courier, monospace"><b>/** ... */</b></font> (long).<br>
<br>
Since APL has no multiline comments we have only <b>⍝</b> and
then <b>⍝⍝</b> would be the corresponging Doxyhen marker.<br>
<br>
If course we can make the <b>)</b><b>HELP</b> mechanism tolerant
to support different markers at the same time. But the rules<br>
should be understoof and fixed before I start with the
implementation.<br>
<br>
What I don't like is when the start marker is the same as the end
marker, because it introduces useless error<br>
cases (like missing end marker).<br>
<br>
I would also argue that we should separate two things:<br>
(1) the distinction between code extraction comments and normal
comments, and<br>
(2) the tagging inside a </font><font face="Helvetica, Arial,
sans-serif">code extraction comment.<br>
<br>
(1) should follow the language (i.e. APL) rules while (2) follows
the code extraction rules.<br>
<br>
Following that would make:<br>
<br>
</font><font face="monospace, monospace">⍝ Begin a transaction.</font><font
face="Helvetica, Arial, sans-serif"><br>
<br>
a normal comment.<br>
</font><br>
BTW for those of you looking for coding tasks, contributing APL
support to Doxygen would<br>
be a useful thing to do. I felt like doing that myself, but I
haven't found the time to do it yet.<br>
<br>
Best Regards,<br>
Jürgen Sauermann<br>
<br>
<font face="Helvetica, Arial, sans-serif"><br>
Which would make . a start/end marker.<br>
</font><font face="Helvetica, Arial, sans-serif"><br>
</font>
<div class="moz-cite-prefix">On 04/18/2017 04:56 AM, Elias Mårtenson
wrote:<br>
</div>
<blockquote
cite="mid:CADtN0W+YGnsyMF-sVZZyKQJbmhs_HD9aLP=***@mail.gmail.com"
type="cite">
<div dir="ltr">Sorry for following up to my own email, but I
forgot to mention one thing:
<div><br>
</div>
<div>I have absolutely no particular attachment to the choice of
using ⍝⍝. I'm OK with any format, but the important part is
that it's clearly distinct from any normally occurring
comments or code.</div>
<div><br>
</div>
<div>If I remember correctly, this was discussed several years
ago and one of the proposals was to use ⍝-, like this:</div>
<div><br>
</div>
<div>
<div><font face="monospace, monospace">∇Z←SQL∆Begin db</font></div>
<div><font face="monospace, monospace">⍝-<br>
</font></div>
<div><font face="monospace, monospace">⍝ Begin a transaction.</font></div>
<div><font face="monospace, monospace">⍝-<br>
</font></div>
<div><font face="monospace, monospace">⍝ This is a normal
comment that is not part of the documentation.<br>
</font></div>
<div><font face="monospace, monospace">  Z←⎕SQL[5] db</font></div>
<div><font face="monospace, monospace">∇</font></div>
</div>
<div><br>
</div>
<div>I personally find the ⍝⍝ format to be more readable though,
but that's just my personal taste.</div>
<div><br>
</div>
<div>Regards,</div>
<div>Elias</div>
</div>
<div class="gmail_extra"><br>
<div class="gmail_quote">On 18 April 2017 at 10:49, Elias
Mårtenson <span dir="ltr">&lt;<a moz-do-not-send="true"
href="mailto:***@gmail.com" target="_blank">***@gmail.com</a>&gt;</span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">Hello David,
<div><br>
</div>
<div>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:</div>
<div>
<ol>
<li>The documentation block is prefixed by ⍝⍝</li>
<li>The first line is the short summary.</li>
</ol>
<div>Using a special format to describe documentation is
very important. The reason is that <i>you absolutely
don't want to display “normal” comments as
documentation</i>. Using ⍝⍝ tells the system that
the person who wrote the documentation intended this
to be documentation, and not just merely a plain
comment.</div>
</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>This system of having dedicated documentation strings
is very well established in multiple languages, for
example:</div>
<div>
<ul>
<li>Java (uses /**)</li>
<li>C++ (doxygen, uses /**)</li>
<li>Python (uses triple-quote """like this""". An
empty string conveniently is a no-op in Python)</li>
<li>Common Lisp ("a plain string" as the first form,
like Python this ends up being a no-op)</li>
<li>Emacs Lisp (same syntax as Common Lisp, the
documentation is tightly integrated in the help
system)</li>
</ul>
<div>As you can see, this is nothing new, and has proven
to be incredibly useful in multiple languages.</div>
</div>
<div><br>
</div>
<div>Finally, this is not merely a good idea. It's also
actively working in the GNU APL Emacs mode today, and if
you want to have integrated documentation in the editor
you need to follow this convention anyway.</div>
<div><br>
</div>
<div>Regards,</div>
<div>Elias</div>
</div>
<div class="HOEnZb">
<div class="h5">
<div class="gmail_extra"><br>
<div class="gmail_quote">On 18 April 2017 at 09:05,
David B. Lamkins <span dir="ltr">&lt;<a
moz-do-not-send="true"
href="mailto:***@lamkins.net" target="_blank">***@lamkins.net</a>&gt;</span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">Thank
you to everyone who contributed to the recent
extension to )HELP. This'll be far more convenient
that flipping between APL and two PDF references.<br>
<br>
Regarding help for user-defined functions, I'd
like to offer a suggestion:<br>
<br>
I've noticed quite a bit of talk about adopting
syntax and/or semantics (e.g. tags) from the
conventions used by other languages and
documentation extractors.<br>
<br>
I'd like to suggest that it's in everyone's
interest for the format of header comments to
remain as neutral as possible, leaving open the
possibility for everyone to adopt (or invent)
whatever convention they prefer.<br>
<br>
The way I see it, the only real concern should be
how to delimit the end of a header comment. I'd
like to suggest that every lamp line starting with
the first line of the function is a header comment
regardless of indentation or markup. The end of
the header comment is simply the first non-lamp
line; this could be either a line of APL code or
an empty line (and I prefer visual equivalence, so
a line of only whitespace would be considered
empty for this purpose). If the first line of the
function is visually empty or a line of APL code,
then the function has no header comment.<br>
<br>
Again, thanks!<br>
<span class="m_-1944483128219150452HOEnZb"><font
color="#888888"><br>
David<br>
<br>
--<br>
I've found my niche.  If you're wondering why
I'm not there, there was<br>
this little hole in the bottom ...<br>
                -- John Croll<br>
<br>
</font></span></blockquote>
</div>
<br>
</div>
</div>
</div>
</blockquote>
</div>
<br>
</div>
</blockquote>
<br>
</body>
</html>

[Peter Teeson]

Actually for a slightly different POV

Some criteria for writing maintainable APL from my days at Sharp:
a) Extracting only the comments should allow a competent APL’er to provide the missing code.
b) No horrendous one-liners
c) Code and comments may not exceed a single 8.5 x 11 sheet of paper.

The reason is that you absolutely don't want to display “normal” comments as documentation.

FWIW

[Elias Mårtenson]

I'm not sure that's even a different point of view. What you listed is
common sense and I hope everybody who is developing code for more than one
person abides by it.

It also doesn't conflict with the idea of docstrings. What the double lamp
signifies is the difference between documentation explaining how to use a
function, vs. documentation explaining how the function accomplishes what
it does.

Regards,
Elias

Post by Peter Teeson
Actually for a slightly different POV

a) Extracting only the comments should allow a competent APL’er to provide
the missing code.
b) No horrendous one-liners
c) Code and comments may not exceed a single 8.5 x 11 sheet of paper.
The reason is that *you absolutely don't want to display “normal”
comments as documentation*.
FWIW

[David B. Lamkins]

Post by Elias MÃ¥rtenson
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
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.

Post by Elias MÃ¥rtenson
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.

Post by Elias MÃ¥rtenson
This system of having dedicated documentation strings is very well established
• 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.

[Elias Mårtenson]

Post by David B. Lamkins
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.

Post by David B. Lamkins
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.

Post by David B. Lamkins
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.

Post by David B. Lamkins

Post by Elias MÃ¥rtenson
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.

Post by David B. Lamkins
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

Post by David B. Lamkins
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

[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

Post by David B. Lamkins
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.

Post by Elias MÃ¥rtenson
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.
∇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

[Juergen Sauermann]

<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<font face="Helvetica, Arial, sans-serif">Hi David,<br>
<br>
I believe the initial question was whether we should adopt the
Doxygen style of comments or<br>
the toronto toolkit style.<br>
</font><br>
So this means do we prefer to be locked into Doxygen or into the
toronto toolkit?<br>
<br>
We could of course adopt a third style so that we are neither locked
into Doxygen nor into<br>
the toronto toolkit, but that would make the comments the most
useless.<br>
<br>
I cannot judge how powerful the comment extracting capabilities of
the toronto toolkit<br>
are, but I know that those of Doxygen are quite impressive: caller
graphs, call graphs,<br>
varous lists (functions, variables), different output formats (HTML,
PDF, TeX, and a few more).<br>
<br>
If the toronto toolkit is also capable of all this then fine.
Otherwise we should push for Doxygen<br>
support for APL. Right now Doxygen does not have support for APL but
it seems quite feasible<br>
to add that if we contribute to the Doxygen project instead of just
asking them for supporting APL.<br>
<br>
And of course in the end it should be the users that decide which
format they prefer (if any).<br>
<br>
/// Jürgen<br>
<br>
<br>
<div class="moz-cite-prefix">On 04/18/2017 05:57 PM, David B.
Lamkins wrote:<br>
</div>
<blockquote cite="mid:***@morganthe" type="cite">
<pre wrap="">On Tue, Apr 18, 2017 at 10:49:28AM +0800, Elias Mårtenson wrote:
</pre>
<blockquote type="cite">
<pre wrap="">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.
</pre>
</blockquote>
<pre wrap="">
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.

</pre>
<blockquote type="cite">
<pre wrap="">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.
</pre>
</blockquote>
<pre wrap="">
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.

</pre>
<blockquote type="cite">
<pre wrap="">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.
</pre>
</blockquote>
<pre wrap="">
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.

</pre>
</blockquote>
<br>
</body>
</html>

[e***@gmx.com]

will i have to install doxygen to use this?? say no


On Tue, 18 Apr 2017 19:56:25 +0200

Post by 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
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
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
• 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.

[Juergen Sauermann]

<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<font face="Helvetica, Arial, sans-serif">Hi,<br>
<br>
No. This is just to be able to use the same comments in <b>Doxygen</b>
and in the <b>)HELP</b> command of GNU APL.<br>
<br>
Likewise, if we go for toronto toolkit then we would be able </font><font
face="Helvetica, Arial, sans-serif">to use the same comments in
the <b>to</b><b>r</b><b>onto toolkit</b> and<br>
in the <b>)HELP</b> command of GNU APL.<br>
<br>
And pointing out again that <b>Doxygen</b> currently does not
support APL at all, but <b>maybe</b> we can change that.<br>
<br>
Best Regards,<br>
Jürgen Sauermann<br>
<br>
<br>
</font>
<div class="moz-cite-prefix">On 04/18/2017 08:05 PM, <a class="moz-txt-link-abbreviated" href="mailto:***@gmx.com">***@gmx.com</a>
wrote:<br>
</div>
<blockquote cite="mid:***@gmx.com"
type="cite">
<pre wrap="">
will i have to install doxygen to use this?? say no


On Tue, 18 Apr 2017 19:56:25 +0200
Juergen Sauermann <a class="moz-txt-link-rfc2396E" href="mailto:***@t-online.de">&lt;***@t-online.de&gt;</a> wrote:

</pre>
<blockquote type="cite">
<pre wrap="">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.


</pre>
</blockquote>
<pre wrap="">

</pre>
</blockquote>
<br>
</body>
</html>

[e***@gmx.com]

Thanks - this help is a great addition - i vote doxygen comment method -

btw I meant to say 'Please say No' just 'say no' missed the inflection of I never got use to info over man and certainly not doxygen over latex :)

On Tue, 18 Apr 2017 20:29:38 +0200

Hi,
No. This is just to be able to use the same comments in Doxygen and in the )HELP command of GNU APL.
Likewise, if we go for toronto toolkit then we would be able to use the same comments in the toronto toolkit and
in the )HELP command of GNU APL.
And pointing out again that Doxygen currently does not support APL at all, but maybe we can change that.
Best Regards,
Jürgen Sauermann
will i have to install doxygen to use this?? say no
On Tue, 18 Apr 2017 19:56:25 +0200
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
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
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
• 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.

[e***@gmx.com]

This all looks great btw - great addition to system


On Tue, 18 Apr 2017 10:49:28 +0800

Post by Elias MÃ¥rtenson
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
1. The documentation block is prefixed by ⍝⍝

what happens with ⍝⍝ ∇ <snicker>

Post by Elias MÃ¥rtenson
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.
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.
This system of having dedicated documentation strings is very well
- 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.
Finally, this is not merely a good idea. It's also actively working in the
GNU APL Emacs mode today, and if you want to have integrated documentation
in the editor you need to follow this convention anyway.
Regards,
Elias

Post by David B. Lamkins
Thank you to everyone who contributed to the recent extension to )HELP.
This'll be far more convenient that flipping between APL and two PDF
references.
I've noticed quite a bit of talk about adopting syntax and/or semantics
(e.g. tags) from the conventions used by other languages and documentation
extractors.
I'd like to suggest that it's in everyone's interest for the format of
header comments to remain as neutral as possible, leaving open the
possibility for everyone to adopt (or invent) whatever convention they
prefer.
The way I see it, the only real concern should be how to delimit the end
of a header comment. I'd like to suggest that every lamp line starting with
the first line of the function is a header comment regardless of
indentation or markup. The end of the header comment is simply the first
non-lamp line; this could be either a line of APL code or an empty line
(and I prefer visual equivalence, so a line of only whitespace would be
considered empty for this purpose). If the first line of the function is
visually empty or a line of APL code, then the function has no header
comment.
Again, thanks!
David
--
I've found my niche. If you're wondering why I'm not there, there was
this little hole in the bottom ...
-- John Croll