documentation (Re: Re : [Caml-list] Not Rocket Science)

[Oliver Bandel <oliver@first.in-berlin.de>]

Zitat von Adrien <camaradetux@gmail.com>:

> There are working binding to gnuplot in fact :
>   http://sourceforge.net/projects/ocaml-gnuplot/
>
> And there is also plplot and another one which name I can't remember.
>
> As a side note, I recently used gnuplot but not with these bindings :
> a very easy way to create plots with gnuplot is to write the plot
> coordinates to a file (in human-readable format) and then run gnuplot
> with the file as argument. That's as easy as :
>   let log_c=open_out_bin "./results/pour_gnuplot.txt" in
>   Printf.fprintf log_c "%d %f\n" !i !mistake
>   (* this is an excerpt from an actual code *)
[...]

Using gnuplot is easiest to start with,
but when it comes to more sophisticated needs,
you soon will be stopped.

plplot is more powerful here, so this is nice even
for complex things (e.g. 3D-stuff with text also
rotated in 3D). But plplot's documentation is noc ecomplete,
and IMHO the usage of only 2D-arrays for 3D-data seems to be
not the best design decision. So the API looks not that good.
The documentation is big, but some necessary things are
not explained. And the examples in use use functions,
that are not explained in the documentation.

So, one has to do reverse engineering, isnetad of straightforwad
using the docs and start to code.

But this is a common problem in nearly all programming stuff,
open or closed source, applications or libraries...

IMHO the biggest necessity is better documentation.
This also gholds for a lot of OCaml-libraries, like
Camlimages and others.

It's fine to have the documentation showing all
types and values.
It's even better to explain, what modules can plugged in in which other
modules, meaning here: which types of the modules in use fit together.

yes, one can find out that by reading all docs and
re-organizing the stuff. A documentation IMHO should help the reader
here.

A documentation can reflect the possible plug-in's.
I'm not a monads-specialits, but as far as I have grasped
the concept (on the surface I think), it is this way,
how also a documentation could be done:

   Plug A in into B or C and it will work this way: ...
   Plug in C in F or Z, and it will work in this way....
   Plug in F in G and it will work like ...
   Plug in C into U or W and it will work also: it will do...


   So, you can Plug in A into C, and C into U or W.

And this can be shown as a graphic.
I have heard, computers in the year 2008 can use text as well
as graphics... ;-)

This would enhance readability and adaption of new things.

But it's also possible to only show the interfaces...
...when there are many module with types that can be used
in many ways, the reader needs more time to get an overview.

So, only some hints on how to make things more clear.

The above mentioned is meant in gerenal,
but I had tried to use CamlImages twice,
and there was a while between both trials, and
I ended up now in using jpeglib with C. ;-(
(But I already has used jpeglib a while ago,
 so this compoarision is a littlebit unfair ;-))


Ciao,
  Oliver