Hi,
the whole comment would go into Doxygen as one block.
Doxygen has different output formats (HTML, Tex, PDF so HTML markup
would not work for the
others. But they have their own markup link \b for bold.
I downloaded the Doxygen sources. It looks feasible to add a language.
Not trivial but
not impossible either. I guess a volunteer would be good! Some time ago
(30 years or so)
I have seen really huge APL workspaces that were almost impossible to
understand.
Having call graphs for those would have been a great thing at that time.
/// Jürgen
On 07/31/2014 06:32 PM, 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. :-)
Should be first line be the "summary"? Should we allow leading spaces
before the ⍝⍝?
Should we assume that the content of the doc comment is HTML or some
other kind of markup?
Regards,
Elias
On 1 August 2014 00:19, Juergen Sauermann
<juergen.sauerm...@t-online.de <mailto:juergen.sauerm...@t-online.de>>
wrote:
Hi Elias,
the standard Doxygen way would be ⍝⍝< I believe.
But I doubt that we will get Doxygen support for APL unless we
contribute it ourselves (their
wishlist is somewhat lengthy and APL is most likely not on their
top-10 list).
Another way would be to define our own marker and then translate
that to a language
that Doxygen understands. Because ⍝⍝< looks a bit odd I would
propose ⍝⍝ instead. So we
could write an APL function like this:
∇Z←foo B
⍝⍝ foo returns B
Z←B
∇
And when it comes to Doxygen we could output it in Doxygen C
syntax like this:
/**
foo returns B
Z←B
**/ foo(Z, A, B); // fake C function declaration
This approach would have some limitations compared to direct APL
support.
But some things that I find useful such as call and caller graphs
should work.
/// Jürgen
On 07/31/2014 05:38 PM, Elias Mårtenson wrote:
Right now, yes. It is the first comment block. If you want to
define a more complex format, please go ahead. I'll update the
Emacs code to make something clever with it. :-)
On 31 July 2014 23:26, Juergen Sauermann
<juergen.sauerm...@t-online.de
<mailto:juergen.sauerm...@t-online.de>> wrote:
Hi Elias,
so its simply an APL comment at the beginning of the function?
I would still propose some kind of marker that distinguishes
it from normal APL comments
(and in order to make it Doxygen compatible).
/// Jürgen
On 07/31/2014 05:03 PM, Elias Mårtenson wrote:
Docstrings is documentation for a function, embedded in the
function definition itself, as discussed in a previous
thread last week or so.
Here's an example for the Connect command:
https://github.com/lokedhs/apl-sqlite/blob/master/SQL.apl#L20
The Emacs mode uses this to provide integrated
documentation, and I've also written an APL function to
extract this information (not ready for common use):
https://github.com/lokedhs/apl-tools/blob/master/doc.apl
Regards,
Elias
On 31 July 2014 22:59, Juergen Sauermann
<juergen.sauerm...@t-online.de
<mailto:juergen.sauerm...@t-online.de>> wrote:
Hi Elias,
I changed/removed the _5000 functions as proposed
What are docstrings?
/// Jürgen
On 07/31/2014 09:36 AM, Elias Mårtenson wrote:
I checked out the helper library for FILE_IO. Very nice.
First of all, how about adding docstrings in the same
form as the SQL library? I'm willing to help writing it
if you want.
Secondly, I wonder why some functions are defined the
way they are though. For example, wouldn't it make more
sense to define FIO∆fread like this instead, and then
skip the FIO∆fread_5000 function:
∇Zi ← blocksize FIO∆fread Bh
→(0≠⎕NC 'blocksize')/use¯blocksize
blocksize ← 5000
use¯blocksize:
Zi ← blocksize FILE_IO[6] Bh
∇
Regards,
Elias
