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 <da...@lamkins.net> 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 <dlamk...@gmail.com> 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. > > > > > > > > > >
