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