Re: [Bug-apl] )HELP ...

[enztec]

will i have to install doxygen to use this??  say no


On Tue, 18 Apr 2017 19:56:25 +0200
Juergen Sauermann <address@hidden> wrote:

> Hi David,
> 
> I believe the initial question was whether we should adopt the Doxygen style 
> of comments or
> the toronto toolkit style.
> 
> So this means do we prefer to be locked into Doxygen or into the toronto 
> toolkit?
> 
> We could of course adopt a third style so that we are neither locked into 
> Doxygen nor into
> the toronto toolkit, but that would make the comments the most useless.
> 
> I cannot judge how powerful the comment extracting capabilities of the 
> toronto toolkit
> are, but I know that those of Doxygen are quite impressive: caller graphs, 
> call graphs,
> varous lists (functions, variables), different output formats (HTML, PDF, 
> TeX, and a few more).
> 
> If the toronto toolkit is also capable of all this then fine. Otherwise we 
> should push for Doxygen
> support for APL. Right now Doxygen does not have support for APL but it seems 
> quite feasible
> to add that if we contribute to the Doxygen project instead of just asking 
> them for supporting APL.
> 
> And of course in the end it should be the users that decide which format they 
> prefer (if any).
> 
> /// Jürgen
> 
> 
> On 04/18/2017 05:57 PM, David B. Lamkins wrote:
> On Tue, Apr 18, 2017 at 10:49:28AM +0800, Elias Mårtenson wrote:
> Hello David,
> 
> Having a standardised format is what makes this so useful. The whole point of
> this is to make sure that everybody uses the same convention so third-party
> tools can integrate with the system. If everybody “adopts the convention they
> prefer”, as you suggest, such a system would not be very useful. With regards
> to the format, I think you are exaggerating the complexity a bit. It's really
> only two rules:
> 
>  1. The documentation block is prefixed by ⍝⍝
>  2. The first line is the short summary.
> 
> Using a special format to describe documentation is very important. The reason
> is that you absolutely don't want to display “normal” comments as 
> documentation
> . Using ⍝⍝ tells the system that the person who wrote the documentation
> intended this to be documentation, and not just merely a plain comment.
> 
> Is "all the leading comment lines until the first non-comment line" that 
> complex? I'm just trying to be precise about what's a "header comment" and 
> what's not.
> 
> Given the double-lamp convention, what's the expected behavior if I drop a 
> double-lamp comment in the middle of my APL code? Is that still part of the 
> header comment?
> 
> The problem with adopting a convention from an existing tool is that it locks 
> everyone into using that tool, whether it's their preference to use that tool 
> or not. Because GNU APL can deal with program text stored on a Unicode file, 
> any tool can process that file. I think it's presumptive to declare any 
> particular markup format as "standard". Let the user decide.
> 
> The Emacs mode dynamically pops up this documentation string whenever the
> cursor is on top of a function name, and you really don't want arbitrary
> comments to be displayed there.
> 
> What's an "arbitrary" comment? In my proposal, the comments at the top of the 
> function are the header comment. Every comment after the first line of APL 
> code or empty line is not part of the header comment.
> 
> The only thing the double-lamp convention does is to let you use grep rather 
> than a simple parsert that can identify the start of a user-defined function 
> and a comment-only line. That's really not difficult. And of course the 
> "grep" approach opens up questions like the one I raised above about "header" 
> comments tucked into the middle of a function.
> 
> This system of having dedicated documentation strings is very well established
> in multiple languages, for example:
> 
>   • Java (uses /**)
>   • C++ (doxygen, uses /**)
>   • Python (uses triple-quote """like this""". An empty string conveniently is
>     a no-op in Python)
>   • Common Lisp ("a plain string" as the first form, like Python this ends up
>     being a no-op)
>   • Emacs Lisp (same syntax as Common Lisp, the documentation is tightly
>     integrated in the help system)
> 
> As you can see, this is nothing new, and has proven to be incredibly useful in
> multiple languages.
> 
> Let's not conflate the importance of documentation with the syntax of the 
> comments. All I'm arguing for is to not impose a special syntax on "header" 
> comments. A header comment is simply the comments at the top of the function. 
> Period. Doesn't need to be any more complex than that.
> 
>