[Dovecot] busy / developers documentation

[Thomas Hummel]

On Tue, Dec 01, 2009 at 05:39:55PM -0600, Timo Sirainen wrote:
> Just thought I'd mention that I probably won't be answering mails very actively this week while I'm in San Antonio (and I was kind of busy last week too). Hopefully I'll get back to answering/bugfixing next week..
> 
> I also started writing developers documentation to http://wiki.dovecot.org/Design. Comments welcome. Some things I had planned next:
> 
>  - istream internals
>  - lib-storage API docs
>  - ..?

Hello Timo,

Just an idea talking about writing documentation :

When I looked at the authentication code (using LDAP) back in the 1.1 version,
it took me some time to understand the function call cascading, especially with
the "callback"/"context" mechanism which I found clever but hard to follow. 

I came to the understanding (hope I was right) that you were using some kind of
layered architecture, which went something like this :

  "low level" < ldap_request level < passdb_ldap_request level < auth_request level < auth_request_handler level < auth_client_connection level < "high level"

where :

     . passdb_ldap_request == passwd checking
     . auth_request == parameters (user, password, state) and internal management of the request
     . auth_request_handler == building of the answer of the request
     . auth_client_connecion == sending to the authentication client (imap-login)

...

  . callback : a pointer in a lower level to a function in an higher level

  . context : what links "objects" of those layers eachother

I was thinking that, if my understanding is correct, some overview from you of
such an architecture would be of great help for those who want to understand
the code.

Thanks.

-- 
Thomas Hummel 	    | Institut Pasteur
<hummel at pasteur.fr> | Pôle informatique - systèmes et réseau