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

List:       koffice-devel
Subject:    Re: koffice api documentation
From:       Nicolas Goutte <nicolasg () snafu ! de>
Date:       2003-12-23 21:41:17
[Download RAW message or body]

On Tuesday 23 December 2003 11:15, Marc Heyvaert wrote:
> Hello,
>
> I may have mentioned this before...
>
> It is relatively quiet at work for the moment, so I'm
> trying to do something useful like browsing in some
> kspread code :-)
>
> 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.
>
> It comes down to this...If you precede some identifier
> with some documentation, delimited in a 'special' way
> (e.g. /** or /*! or three successive lines of //,
> etc.) it will be part of the docs, otherwise not.
> Because not everyone follows this strictly, there are
> some very important classes, memberfunctions, etc that
> go undocumented.
>
> Now I understand that it can be usefull to leave some
> unimportant bits undocumented in such a tool to keep
> thingsclear and consistent, but in this case it is
> totally at random. So I suggest documenting everything
> using a parameter in doxygen. I quote the manual :
>
> BEGIN QUOTE
> If the EXTRACT_ALL option is set to NO in the
> configuration file (the default), then doxygen will
> only generate documentation for documented members,
> files, classes and namespaces.
> END QUOTE
>
> So it seems to me that if EXTRACT_ALL were to be set
> to YES all would be ok.
>
> Can somebody look into this pls? And/or give some
> feedback
>
> Regards
>
> Marc

It has been written umpteenth times that the docapi comments should be fixed. 
However it is always the same problem as to where to find the manpower.

Until recently, only the public API was documented, KWord, KSPread and such 
were not. Someone has changed the doxygen run on the KOffice site so that it 
now process all classes *not* marked as @internal (So in theory, if all 
classes were correctly marked, not any KSpread class should be displayed.)

(I, personally, am not sure if the @internal classes should not be displayed.)

So if you volunteer to fix the comments, fine. (Sorry I am answering before 
having had time to really read all emails of this thread (including this one), 
sorry if I am repeating or telling something totally at the opposite of what 
was written.)

Have a nice day!

PS.: you can also consider that the Wen SIte is badly maintained, so if you 
want to help here fine too! See http://www.koffice.org/developer/website/

>
> __________________________________
> 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

_______________________________________________
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]