OK, I'll update the Emacs code to do this. Regards, Elias
On 1 August 2014 18:11, Juergen Sauermann <juergen.sauerm...@t-online.de> wrote: > Hi, > > from my side - yes. > > /// Jürgen > > > > > On 08/01/2014 12:00 PM, Elias Mårtenson wrote: > > So, should we settle for double ⍝ then? In other words, like this: > > ∇Z←foo X > ⍝⍝ Doc comment > ⍝⍝ This one too > ⍝ But not this one > Z←X+1 > ∇ > > Regards, > Elias > > > On 1 August 2014 17:56, Juergen Sauermann <juergen.sauerm...@t-online.de> > wrote: > >> Hi, >> >> the ⍝⍝ comes from way doxygen works. >> >> For example, // is a C/C++ comment while /// is a C/C++ comment >> understood by doxygen. >> >> In VHDL, -- is a VHDL comment while --- is a VHDL comment understood by >> doxygen. etc. >> >> I didn't want to go as far as using ⍝⍝⍝ (and no need to since ⍝ alone is >> a comment. >> >> Looking at the output of doxygen, it is definitely needed to be able to >> distinguish between >> normal comments and doxygen comments. Otherwise well-documented programs >> will look >> rather odd in the generated documentation. >> >> Doxygen also distinguishes between long and short comments. Not sure if >> we need that; >> with short comments alone you can produce pretty good documentation. >> >> /// Jürgen >> >> >> >> On 08/01/2014 01:01 AM, David B. Lamkins 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. >>> >>> >>> >>> >> > >
