Re: [AD] Proposed changes for Allegro 5 (6?)

[Stepan Roh <stepan@xxxxxxxxxx>]

On Thu, 29 Nov 2001, Sven Sandberg wrote:

> Stepan Roh wrote:
> > But in-source documentation is good thing.

I was talking as Java programmer where packages and interfaces solve most
of your problems.

> There are some problems with it too:
>  - Is it possible to make sections be structured another way than the
> source files? It would be confusing if there was one section for the
> functions in gfx.c and another for the functions in graphics.c, or if
> load_bmp(), load_pcx() etc were in different sections.
>  - Some functions are defined in different files depending on which
> platform they are on, so there's no unique natural place to put the
> documentation on.
>  - allegro._tx contains several generic sections that discuss
> programming principles (e.g. "Bitmap objects"), or non-api stuff (e.g.
> "Makefile targets"), that would not fit in naturally in any source file.

>  - allegro._tx is not the only file generated by makedoc: there are
> totally 8 files mathching allegro/docs/src/*._tx. So we need something
> to compile help that does not come from a source file anyway.

In-source documentation could be add-on only. Maybe hack makedoc to be
able to parse sources and found function descriptions? Like :

@source_parse src/dir/source.c:function_name

But that is too complicated to do.

Have a nice day.

Stepan Roh