[prev in list] [next in list] [prev in thread] [next in thread] 

List:       koffice-devel
Subject:    Re: koffice api documentation
From:       Marc Heyvaert <marc_heyvaert () yahoo ! com>
Date:       2003-12-23 11:23:04
[Download RAW message or body]

Hello

Yes and no,

I understand your point and that of Thomas too, not
all comments are suitable for the api documentation,
but :
1. The documentation serves 2 purposes IMHO : to make
the whole api visible (which is not the case now) and
to make the 'relevant' comments visible (which isn't
the case either, because some very important comments,
like e.g. the different types of 'flags' are in the
source code, but not in the docs.

2.I'm obliged now to shuttle back and forth between
the fully referenced docs, the web-based source
reference and the source files. Not very efficient
when you try to understand the code :-)

So I think I will try to put my own docs together with
doxygen, just to get to know the package a littel
better, because what you said about the EXTRACT_ALL
parameter not solving the problem is a bit puzzeling.

Also, am I right to suppose that only the stuff in the
header-files is used by doxygen? If this is so the
solution could be to put all 'important' comments in
the .h files and all the other 'developer' stuff in
the .cc files. Still a lot of work though. I'm willing
to help, but I still haven't foud a way to get this
CVS working :-(

Marc
--- Karl-Heinz Zimmer <khz@kde.org> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> On Dienstag, 23. Dezember 2003 11:15, Marc Heyvaert
> wrote:
> (...)
> > On the KOffice webpage there is a link to the
> online
> > koffice api. Unfortunately this documentation is
> not
> > complete and this has to do (I think) with the way
> > doxygen processes the sourcefiles.
> (...)
> > Because not everyone follows this strictly, there
> are
> > some very important classes, memberfunctions, etc
> that
> > go undocumented.
> (...)
> > So it seems to me that if EXTRACT_ALL were to be
> set
> > to YES all would be ok.
> 
> Since the reason for not everything being in the
> generated docu is the
> lack of /**  */ enframed comments (due to not all
> developers adhering
> to this schema) the way to solve this IMHO is fixing
> the wrong comments
> by turning /* into /** where appropriate.
> 
> I might be wrong but I think just using EXTRACT_ALL
> would not solve
> the problem: lots of 'wrongly' enframed comments
> would still not go
> into the generated documentation then.
> 
> So the (big?) job is: find out which comments should
> be converted
> into Doxygen (JavaDoc) compatible ones and which
> comments should
> NOT be changed - because they are just internal
> remarks that should
> not go into the docu...
> 
> Just my 2 pence.  :)
> 
> Karl-Heinz
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.2.2-rc1-SuSE (GNU/Linux)
> 
>
iD8DBQE/6CMvCcaVnbvggDcRAiBUAJ4oH1wQrr2XmSKdOPMkTc/MfMAVFwCdGjc3
> roQU4nNUGyAblGd3Ir0PEJI=
> =jang
> -----END PGP SIGNATURE-----
> 
> _______________________________________________
> koffice-devel mailing list
> koffice-devel@mail.kde.org
> https://mail.kde.org/mailman/listinfo/koffice-devel


__________________________________
Do you Yahoo!?
New Yahoo! Photos - easier uploading and sharing.
http://photos.yahoo.com/
_______________________________________________
koffice-devel mailing list
koffice-devel@mail.kde.org
https://mail.kde.org/mailman/listinfo/koffice-devel
[prev in list] [next in list] [prev in thread] [next in thread]