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. > > > >
