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