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.
