[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Bug-apl] FILE_IO library
From: |
David B. Lamkins |
Subject: |
Re: [Bug-apl] FILE_IO library |
Date: |
Thu, 31 Jul 2014 16:01:43 -0700 |
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.
- [Bug-apl] FILE_IO library, Elias Mårtenson, 2014/07/31
- Re: [Bug-apl] FILE_IO library, Juergen Sauermann, 2014/07/31
- Re: [Bug-apl] FILE_IO library, Elias Mårtenson, 2014/07/31
- Re: [Bug-apl] FILE_IO library, Juergen Sauermann, 2014/07/31
- Re: [Bug-apl] FILE_IO library, Elias Mårtenson, 2014/07/31
- Re: [Bug-apl] FILE_IO library, Juergen Sauermann, 2014/07/31
- Re: [Bug-apl] FILE_IO library, Elias Mårtenson, 2014/07/31
- Re: [Bug-apl] FILE_IO library, Juergen Sauermann, 2014/07/31
- Re: [Bug-apl] FILE_IO library,
David B. Lamkins <=
- Re: [Bug-apl] FILE_IO library, Elias Mårtenson, 2014/07/31
- Re: [Bug-apl] FILE_IO library, David B. Lamkins, 2014/07/31
- Re: [Bug-apl] FILE_IO library, Elias Mårtenson, 2014/07/31