Hi,
from my side - yes.
/// Jürgen
On 08/01/2014 12:00 PM, Elias Mårtenson wrote:
So, should we settle for double ⍝ then? In other words, like this:
∇Z←foo X
⍝⍝ Doc comment
⍝⍝ This one too
⍝ But not this one
Z←X+1
∇
Regards,
Elias
On 1 August 2014 17:56, Juergen Sauermann
<juergen.sauerm...@t-online.de <mailto:juergen.sauerm...@t-online.de>>
wrote:
Hi,
the ⍝⍝ comes from way doxygen works.
For example, // is a C/C++ comment while /// is a C/C++ comment
understood by doxygen.
In VHDL, -- is a VHDL comment while --- is a VHDL comment
understood by doxygen. etc.
I didn't want to go as far as using ⍝⍝⍝ (and no need to since ⍝
alone is a comment.
Looking at the output of doxygen, it is definitely needed to be
able to distinguish between
normal comments and doxygen comments. Otherwise well-documented
programs will look
rather odd in the generated documentation.
Doxygen also distinguishes between long and short comments. Not
sure if we need that;
with short comments alone you can produce pretty good documentation.
/// Jürgen
On 08/01/2014 01:01 AM, David B. Lamkins wrote:
On Fri, 2014-08-01 at 00:32 +0800, Elias Mårtenson wrote:
So you are basically suggesting using the same principle
as me, just
using two ⍝ symbols instead of one? I'm OK with that. :-)
I have a difficult time imagining a use case that'd have two
different
kinds of comments at the beginning of a function.
However, on the off chance that someone really needs to hide
some of the
header comment from documentation extraction, how about --
rather than
always having to double-up the ⍝ -- recognizing a "cut line". For
example:
∇foo
⍝ This is part of the formal documentation.
⍝ So is this.
⍝ And all subsequent lines up to the cut:
⍝--
⍝ The ⍝-- is the cut line. That line and all
⍝ immediately following comment lines are
⍝ omitted from the formal documentation.
⍝ I showed the cut line by itself; there's no
⍝ strong reason to not allow (ignored) text
⍝ on the same line.
statement1
statement2
⍝ This comment follows an APL statement, so
⍝ is not part of the formal documentation of
⍝ this function.
∇
Should be first line be the "summary"? Should we allow
leading spaces
before the ⍝⍝?
I'm not convinced of the value of a summary, but would rather
not be
limited to one line.
Leading whitespace should always be insignificant.
Should we assume that the content of the doc comment is
HTML or some
other kind of markup?
I'm not at all fond of HTML markup as program documentation. It's
cumbersome and ugly and interferes with reading of the source
code.
Also, mixed syntaxes tend to confuse syntax-aware text editors.
If there's a strong need for markup, please consider a lightweight
syntax. Emacs docstrings are a good example. A small subset of
Markdown
would also be reasonable, IMO.
