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