Re: [Bug-apl] FILE_IO library

[Elias Mårtenson]

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 <address@hidden> 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.