[dev] Fancy Horde/Imap_Client documentation

[Jan Schneider]

Zitat von Michael M Slusarz <slusarz at horde.org>:

> Finally.  It's about time.
>
> Initial implementation has been placed here:
>
> http://dev.horde.org/imap_client/
>
> (Looks a bit like the Routes documentation for some reason...)
>
> Not sure if this is the best place to store this.  Comments welcome.  
>  And ideas how to link from our main www.horde.org pages is also  
> welcome.
>
> Also would be interested to hear thoughts on what else to put on  
> there.  Obviously the examples page needs to be fleshed out more,  
> but I'm not going to spend the time doing too much unless/until  
> people actually start using it.  So if anybody wants examples of a  
> certain feature, now is the time to speak up.

That's a great start! The examples could use a few more inline  
comments, to better explain which variable holds what, and what each  
used method returns.

Generally I think the documentation is spread in too many places.  
While the Routes layout looks nice, it's hard to maintain. And we  
already have the tools in horde-components to *distribute* docs to  
several places, while *maintaining* it in a single place.
Library docs should be completely maintained in the wiki. It's easier  
to edit, and contributions are much easier too. The horde-components  
script can pull those docs into the package's doc/ folder. From their,  
they will build website docs on www.horde.org. See Horde_Argv for an  
example.
This way the docs are available and in sync whereever the user needs  
them. And we don't really need a 4th place for docs.
-- 
Jan Schneider
The Horde Project
http://www.horde.org/