will i have to install doxygen to use this?? say no
On Tue, 18 Apr 2017 19:56:25 +0200
Juergen Sauermann <juergen.sauerm...@t-online.de> 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.
>
>
