Re: [Bug-apl] FILE_IO library

[Juergen Sauermann]

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 <address@hidden> 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 <address@hidden> 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 <address@hidden> 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