GnuCash developer documentation

[Derek Atkins]

I agree.

I would MUCH rather see documentation in the header files than in the
sources.  The sources should be _commented_ so you understand how a
function works internally (i.e. what the implementation is), but the
FUNCTIONAL INTERFACE is defined in the header file.  THAT is where the
INTERFACE documentation should live.

When I want to khow about the interface for xaccTransGetSplits(), I
want to be able to read Transaction.h -- I do NOT want to have to
grovel through Transaction.c to figure out how the function works.

-derek

Christian Stimming <stimming@tuhh.de> writes:

> Wow. This doxygen stuff is gonna be cool :-) Thanks a lot, Benoit.
>=20
> On Samstag, 23. November 2002 21:09, Benoit Gr=E9goire wrote:
> > The header vs source debate is easily solved in doxygen.  You put a /br=
ief
> > doxygen comment above the function declaration in the header, which is a
> > single sentense describing the function.  That sentense in unlikely to
> > change very much over time.
> >
> > In the source, for the same function, you write the detailled descripti=
on
> > and usage, parameters and return value.  This is what is likely to chan=
ge
> > over time.
>=20
> Err... I would definitely prefer to have the *full* function's documentat=
ion=20
> *in the header*. What do developers want to know about functions? They wa=
nt=20
> one sentence saying what this thing is for. And they need to understand w=
hat=20
> each function argument does. And they might need even more detailed=20
> information about how this function is supposed to be called and used.
>=20
> I would especially consider the function argument explanation to be reall=
y=20
> important, if the in-place comments should really help developers. I thin=
k=20
> this is not an overly burden in the amount of file changes, since e.g. if=
 the=20
> arguments change the header file has to be changed anyway.
>=20
> > That way there is enough doc in the header to have a basic idea of what=
 the
> > function does, and if the developer wants more info, he can just fire up
> > his web browser and look at the cross referenced doxygen doc.
>=20
> IMHO not really. A developer who is really down at coding will probably p=
refer=20
> to have the documentation right in front of him, right in the header file=
 of=20
> the function he's looking at. The web browser doc OTOH is really great fo=
r=20
> getting the greater picture, and to look up the really difficult things, =
and=20
> during phases of more conceptual work. Blablabla. Whatever (getting late=
=20
> here)... I'd vote for the complete function documentation right next to t=
heir=20
> declarations, in the header file.
>=20
> Anyway, this docs are gonna be cool. Way to go, Benoit!
>=20
> Christian
>=20
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel@lists.gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel

--=20
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord@MIT.EDU                        PGP key available