Re: [Bug-apl] FILE_IO library

[Elias Mårtenson]

Oh yeah, now that you mention it I remember seeing the same thing. Blank lines gets eaten when the function is defined using ⎕FX. You can see that when using the function editor in the Emacs mode.

On 1 August 2014 10:11, David B. Lamkins <address@hidden> wrote:

One caution about blank lines: I seem to have tripped on quad-FX choking
on empty lines. (This would've been in the case where the argument is a
list, not an array.) I haven't checked recently...

On Fri, 2014-08-01 at 10:03 +0800, Elias Mårtenson wrote:
> 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.
>
>
>
>