Re: [Bug-apl] FILE_IO library

[Elias Mårtenson]

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