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

List:       kde-core-devel
Subject:    Re: Globals, Namespaces, and Documentation
From:       Stephan Kulow <coolo () kde ! org>
Date:       2003-08-20 7:13:32
[Download RAW message or body]

On Wednesday 20 August 2003 00:37, Neil Stevens wrote:
> Now that Doxygen really is replacing kdoc in the library docs, it becomes
> important to fill in those missing features that the current Doxygen docs
> don't support.
> 
> First, the namespace list is missing.  Can that be uncommented please?
> kdoc put namespaces like KNotifyClient and KIO in with the classes, so
> they were always accessible.  Doxygen doesn't, so docs like KNotifyClient
> can't be read unless you know to type the filename/url manually.
> 
> Second, the list of globals is missing.  I'm scouring the Doxygen docs, but
> can't find any hints about how to get one.  So unless KDE 3.2 will be
> adding all the globals like i18n, locate, UserIcon, etc. into a KDE
> namespace, docs for those important functions disappears.
> 
> When I think about it, that namespace seems like a good idea for more
> reasons than just documentation.  Would anyone object to wrapping them all
> in namespace KDE, adding compatibility usings (to be removed for KDE 4)?

I guess I don't object against the KDE namespace now that it's there.
BTW: the doxygen way of documenting such functions are groups that
relate to classes. After all you don't go and think "what global functions can I use",
but you go and think "how do I translate within KDE" -> i18n

I welcome patches or concrete suggestions and I welcome native speakers
writing documention - it's unfortunatly out of my league - and out of my time ;(

Greetings, Stephan

-- 
There may be no I in TEAM, but a M and an E.
[prev in list] [next in list] [prev in thread] [next in thread]