[Ecls-list] Documentation [was: how to cache a cl_object in C?]

[Tobias C. Rittweiler]

Matthew Mondor writes:

> On Thu, 25 Mar 2010 20:06:15 +0800
> yami <yamisoe at gmail.com> wrote:
>
> > BTW: it is a pain to deal with ECL & C, because no good documentation is
> > available.
> > Why there is no good doc work here? Especially for integrating ECL and C
> > programs, which is a selling-point of ECL.
>
> I think that we all agree that the C APIs and FFI should be better
> documented, however this needs work on the part of volunteers to
> complete.
>
> I would like to eventually help but am currently unfamiliar with the
> format used by the current documentation (docbook, I think). I would
> have to look at the tools available for emacs to make editing that XML
> format less troublesome (I find XML not very suited to humans, yet
> suboptimal for software as well.  But as long as the job can be done, I
> guess).  When I have enough free time (possibly in vacations) I might
> look at it, but others are also welcome to send patches :)

I'd start elsewhere:

  a) Decouple the SI from the EXT package.

  b) Following, think what should reside in SI, only, and what can be
     reexported from EXT (and must hence be considered public with all
     consequences of retaining backwards compatibility.)

  c) Hack the ECL's preprocessor (DPP) to allow specifying docstrings
     for functions in the C source code.

  d) Generate API interfaces from the docstrings.

Granted, this is spoken more from a Lisp-centric than C-centric
perspective.

  -T.