It's changed. You can pull the new version of SQL.apl which now has double-lamps for the docstrings.
On 1 August 2014 18:27, Elias Mårtenson <loke...@gmail.com> wrote: > 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. >>>> >>>> >>>> >>>> >>> >> >> >
