From 2e39d37874c4b352f34889e125ffb9ce3bcde888 Mon Sep 17 00:00:00 2001 From: "Dirk-Jan C. Binnema" Date: Mon, 17 Jul 2006 12:33:29 +0000 Subject: [PATCH] * some documentation updates pmo-trunk-r389 --- docs/reference/modest-docs.sgml | 98 +++++++++++++++++++++++++++++---------- 1 file changed, 74 insertions(+), 24 deletions(-) diff --git a/docs/reference/modest-docs.sgml b/docs/reference/modest-docs.sgml index 0680e21..630da5b 100644 --- a/docs/reference/modest-docs.sgml +++ b/docs/reference/modest-docs.sgml @@ -2,13 +2,18 @@ + + + 2006 + Nokia Corporation + + - modest reference manual + modest technical documentation Introduction - modest is a mail user agent (MUA) targetting small devices, in particular Nokia's Nokia 770 Internet Tablet. This document @@ -106,7 +111,7 @@ the ModestConf-class. It is declared in modest-conf.h, and the GConf-based implementation in - modest-conf-gconf.c. As said, there could be + modest-conf.c. As said, there could be different implementations -- nothing GConf-specific is visible in the ModestConf-API. @@ -119,7 +124,7 @@ Account Management is the part of modest that deals with the setting related to sending and receiving of e-mail. We will follow the libcamel-convention of using the - term store for an e-mail storage/retrieval + term store for an e-mail storage/retrieval server, and a transport for a server that transports mail to its destination. @@ -202,9 +207,9 @@ - In the modest-proto.[ch] there are - various functions to check whether something is a valid protocol, and whether - it is a transport of a store. + In modest-proto.[ch] there are various + functions to check whether something is a valid protocol, and + whether it is a transport of a store. Note that server accounts and accounts are relatively independent. While @@ -220,27 +225,55 @@ - - Finding the right transport + + Account Management and Tinymail - One of the interesting topics in designing a mobile e-mail client is - to deal with transports (in - particular, SMTP). The reason for that is that - the majority of SMTP-servers only allow e-mail - from the same network. That means that for example - smtp.some-isp.com will only accept mail from - (MAIL FROM:) - user@some-isp.com, and refuse mail - from user@some-other-isp.com, unless the - recipient (RCPT TO:) is on the same network. + Tinymail needs the information about all configured accounts - and the + mechanism that it uses for that + is TnyAccountStoreIface. We don't want to use + the tinymail-provided TnyAccountStore, but + provide our own implementation + instead: ModestTnyAccountStore. This class + implements the TnyAccountStoreIface-interace in + terms of the aforementioned ModestAccountMgr. - + + + One unexpected function + that ModestTnyAccountStore needs to implement + is tny account_store get_session (to get the + Camel-session). This function must be provided as a public function, + with that exact name. + + + + + + + + + Finding the right transport + + One of the interesting topics in designing a mobile e-mail client is + to deal with transports (in + particular, SMTP). The reason for that is that + the majority of SMTP-servers only allow e-mail + from the same network. That means that for example + smtp.some-isp.com will only accept mail from + (MAIL FROM:) + user@some-isp.com, and refuse mail + from user@some-other-isp.com, unless the + recipient (RCPT TO:) is on the same network. + + + + Coding guidelines - When hacking on \modest, please honour these time-tested coding guidelines. + When hacking on modest, please honour these time-tested coding guidelines. First, please follow the Linux CodingStyle guidelines (/usr/src/linux/Documentation/CodingStyle). @@ -257,21 +290,38 @@ (setq indent-tabs-mode t) (setq c-basic-offset 8) + + Or the equivalent in your favourite editor. - Or the equivalent in your favourite editor. + Lines must not exceed 100 characters. - + - Lines should not exceed 100 characters. + Functions should do one thing, and do it well. In general, functions + should not be much longer than 20-30 lines (except for, say, handling + many different cases in a 'switch'-statement). Files should not get to + big either; if there's more than, say, 800 lines, it probably shows the + codes needs to be refactored a bit. + + Code should compile cleanly + with gcc's -Wall compile option. Of + course this might not always be possible due to problems in dependent + libraries and/or compiler version. Therefore, do not + include -Werror in the standard compile options. + + Global functions (the ones in .h-files) should be commented using gtk-doc. + + + Furthermore, please follow 'conventional wisdom' for programming with GLib/GTK+/GObject. Some things to remember: -- 1.7.9.5