Re: [Lib2geom-devel] API Documentation for lib2geom?

[mgsloan <mg...@gm...>]

Where we have code docs, either it's plain comments before the functions or
in doxygen format.

We are still figuring out the best way to do api docs.  I dislike in-code
comments because they tend to lead to very sparse documentation, often times
with repition of information you already know.  The valuable sort of docs
give you valuable information about the usage and quirks of functions and
classes.  Another problem is the seperation of prose and api docs.  I think
we'd prefer there to be just one manual, readable as a manual and jumpable
like api docs.  Another desirable feature is the ability to jump to the
pretty-printed code definition of a function.  We would also like to
integrate math and illustration.

I haven't found a system that does all this, but then again, I haven't
looked very hard.

-Michael Sloan

On 4/20/07, Sunburned Surveyor <sun...@gm...> wrote:
>
> I'm afraid I must ask another question born of my ignorance as a Java
> developer. Does the lib2geom or inkscape development teams have a standard
> format that they use for API documention? Java has Javadoc, other projects
> use DOxygen, Python has EPydoc...
>
> What do you use for C++?
>
> I always try to write good Javadoc comments for my Java code, and want to
> start building good code documentation habbits as a C++ developer. :]
>
> Thanks for the input.
>