[dev] Fancy Horde/Imap_Client documentation

[Michael M Slusarz]

Quoting Michael J Rubinsky <mrubinsk at horde.org>:

> I normally prefer to read the inline phpdoc while coding with a new  
> library and I felt the existing phpdoc more than met my needs.

For the record... this is exclusively what I use also.  But I  
guarantee we are in the minority - it does take quite a bit of prior  
Horde/PHP knowledge to understand things like file layouts to be able  
to do this.

> However, if it helps, these are the areas that I personally focused  
> on while developing ActiveSync email support, and would have liked  
> to have had some more examples:
>
> - Without giving a lesson on the purpose of MODSEQ values etc...  
> examples on the use of MODSEQ values and the 'changedsince'  
> parameters to fetch recently changed messages.
>
> - Fetching messages that have VANISHED, with a description of why  
> you should provide a list of known UIDs when requesting VANISHED  
> messages (lesson learned the hard way for me).
>
> - Fetching only certain MIME parts.
>
> - Dealing with encoding issues.
>
> - Using the various options of the search/fetch query object to  
> change what is returned.

This last 2-3 are probably the most important.  Right now, the  
documentation is trying to be geared to those people who want an  
alternative to imap's c-client library.  That's what I want to tailor  
the examples to.  I am thinking it might be useful to do some sort of  
mapping from c-client methods -> Imap_Client functionality.

The CONDSTORE/QRESYNC stuff is also what I am very interested in also  
- since we truly are the only solution that provides this.  So it's a  
balancing act of trying to get people to dip their toes into using the  
library vs. informing these people -- and letting the more advanced  
people know -- that our software can handle this also.

michael

___________________________________
Michael Slusarz [slusarz at horde.org]