Re: [Bug-apl] FILE_IO library

[Elias Mårtenson]

I don't really like the cut line. I'd rather see the use of a blank line to make this separation if needed:

∇Z←foo X

  ⍝ Doc comment

  ⍝ This one too

  ⍝ But not this one

  Z←X+1

∇

Now, in your latest example, you went back to using a single ⍝ character as prefix. This is in line with my current implementation. With a double-lamp the above example would look like this:

∇Z←foo X

  ⍝⍝ Doc comment

  ⍝⍝ This one too

  ⍝ But not this one

  Z←X+1

∇

Finally, should there be support for Javadoc-style @-tags? For markup, what kind of system should be used? A lot of people like markdown it seems. I prefer Muse, but that's nowhere near as popular. As long as something is settled on, I can apply that in the documentation buffers in Emacs.

Regards,

Elias

On 1 August 2014 07:01, David B. Lamkins <address@hidden> 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.