From 345ca277f43ebd369dff0cae6cdf4f1501e80bfa Mon Sep 17 00:00:00 2001 From: "Dirk-Jan C. Binnema" Date: Thu, 20 Jul 2006 14:32:34 +0000 Subject: [PATCH] * documentation updates pmo-trunk-r403 --- docs/reference/modest-docs.sgml | 195 +++++++-------- docs/reference/tmpl/modest-account-keys.sgml | 3 + docs/reference/tmpl/modest-account-mgr.sgml | 185 +------------- docs/reference/tmpl/modest-conf-keys.sgml | 70 ------ docs/reference/tmpl/modest-conf.sgml | 2 +- docs/reference/tmpl/modest-edit-window.sgml | 21 -- docs/reference/tmpl/modest-main-window.sgml | 4 +- .../tmpl/modest-tny-header-tree-view.sgml | 2 + .../tmpl/modest-tny-transport-actions.sgml | 1 + docs/reference/tmpl/modest-ui.sgml | 17 +- docs/reference/tmpl/modest-unused.sgml | 264 ++++++++++++++++++++ 11 files changed, 370 insertions(+), 394 deletions(-) diff --git a/docs/reference/modest-docs.sgml b/docs/reference/modest-docs.sgml index 630da5b..2b5afe3 100644 --- a/docs/reference/modest-docs.sgml +++ b/docs/reference/modest-docs.sgml @@ -1,15 +1,13 @@ + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> - - - 2006 - Nokia Corporation - - modest technical documentation + + 2006 + Nokia Corporation + @@ -42,21 +40,21 @@ To summarize the goals for modest: - - target devices with limited amounts of memory ('limited' in 2006 - terms means less than 64Mb, and of which only part can be used for - e-mail); - target Linux/Unix-like environments with GLib/GTK+-based - support; - support multiple user-interface (UIs) with as much code - sharing as possible between the different UIs. + + target devices with limited amounts of memory ('limited' in 2006 + terms means less than 64Mb, and of which only part can be used for + e-mail); + target Linux/Unix-like environments with GLib/GTK+-based + support; + support multiple user-interface (UIs) with as much code + sharing as possible between the different UIs. Like tinymail - and libcamel, modest - is programmed in C, using the GObject-system for - object-oriented (OO) features. For now, it specifically targets \gtk based - UIs (and derivatives like 'Hildon'). + and libcamel, modest + is programmed in C, using the GObject-system for + object-oriented (OO) features. For now, it specifically targets \gtk based + UIs (and derivatives like 'Hildon'). @@ -73,14 +71,14 @@ For modest, the following: modest is a e-mail program - using the tinymail and camel - libraries; + using the tinymail and camel + libraries; modest targets gtk and gconf-based user-interfaces, including the Hildon environment; modest main use-case is in small, mobile device such as the Nokia 770 Internet - Tablet; + Tablet; However, effort is made also to make modest usable as a general-purpose e-mail client on normal desktop computer. @@ -88,14 +86,15 @@ - + Design In this part, we'll discuss the design of various parts of modest. We'll not go into the details of - various APIs in this chapter. Please consul the documentation generated - from the source code (gtk-doc) for that. + various APIs in this chapter. Please consult the documentation generated + from the source code (gtk-doc) for that. + @@ -145,9 +144,9 @@ An account is a named entity consisting of a store and a transport. Note: For our mobile use-cases, - the transport cannot be a static entity, but - may depend on the network connection. That is however not part of - Account Management, so not discussed here + the transport cannot be a static entity, but + may depend on the network connection. That is however not part of + Account Management, so not discussed here A server account is account describing the connection with a specific server. Server accounts come in two type: @@ -161,7 +160,7 @@ - + Code The functions to deal with account and server accounts are @@ -223,53 +222,47 @@ over all smtp-servers and find the right one. - - - - Account Management and Tinymail - - 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. - + + Account Management and Tinymail + + 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 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. + 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. - - - - - - - - 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 @@ -281,14 +274,14 @@ Here are only some additional notes. - + Your editor may help you with this, for example for emacs: - (c-set-style "K&R") - (setq tab-width 8) - (setq indent-tabs-mode t) - (setq c-basic-offset 8) + (c-set-style "K&R") + (setq tab-width 8) + (setq indent-tabs-mode t) + (setq c-basic-offset 8) Or the equivalent in your favourite editor. @@ -297,15 +290,15 @@ Lines must 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. + big either; if there are more than, say, 800 lines, it's a sign that + some refactoring should take place. - + Code should compile cleanly with gcc's -Wall compile option. Of @@ -313,35 +306,35 @@ 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. - - - - + Global functions (the ones in .h-files) must + be commented using gtk-doc. This way, we + generate nice documentation. After installing + (under /usr/local), we can browse the results + with DevHelp. Just + add /usr/local/share/gtk-doc/html to the + DEVHELP_SEARCH_PATH-environment variable. + - Furthermore, please follow 'conventional wisdom' for programming with - GLib/GTK+/GObject. Some things to remember: - - g_new, g_malloc and - friends never return NULL. They terminate - the application if it happens (normally). No need to check - for NULL returns; - g_return_if_fail and friends may be - 'turned off', ie. they are to be used for error checking, - but not for your programming logic - - + Furthermore, please follow 'conventional wisdom' for programming with + GLib/GTK+/GObject. Some things to remember: + + g_new, g_malloc and + friends never return NULL. They terminate + the application if it happens (normally). No need to check + for NULL returns; + g_return_if_fail and friends may be + 'turned off', ie. they are to be used for error checking, + but not for your programming logic + + Object Index - + API Reference diff --git a/docs/reference/tmpl/modest-account-keys.sgml b/docs/reference/tmpl/modest-account-keys.sgml index 52d8b8e..e4fa39a 100644 --- a/docs/reference/tmpl/modest-account-keys.sgml +++ b/docs/reference/tmpl/modest-account-keys.sgml @@ -91,3 +91,6 @@ Definition of keys used to access account properties from the account store. + + + diff --git a/docs/reference/tmpl/modest-account-mgr.sgml b/docs/reference/tmpl/modest-account-mgr.sgml index daf8652..8ff8f04 100644 --- a/docs/reference/tmpl/modest-account-mgr.sgml +++ b/docs/reference/tmpl/modest-account-mgr.sgml @@ -55,6 +55,7 @@ abstraction of the configuration backend used to store the account data. @self: @name: +@server_account: @err: @Returns: @@ -73,17 +74,6 @@ abstraction of the configuration backend used to store the account data. @Returns: - - - - - -@self: -@name: -@err: -@Returns: - - @@ -94,19 +84,6 @@ abstraction of the configuration backend used to store the account data. @Returns: - - - - - -@self: -@account_name: -@type: -@proto: -@only_enabled: -@Returns: - - @@ -114,166 +91,8 @@ abstraction of the configuration backend used to store the account data. @self: @name: +@server_account: @err: @Returns: - - - - - -@self: -@name: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@val: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@val: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@val: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@val: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@val: -@err: -@Returns: - - - - - - - -@self: -@name: -@key: -@val: -@err: -@Returns: diff --git a/docs/reference/tmpl/modest-conf-keys.sgml b/docs/reference/tmpl/modest-conf-keys.sgml index 2eed751..321bdc1 100644 --- a/docs/reference/tmpl/modest-conf-keys.sgml +++ b/docs/reference/tmpl/modest-conf-keys.sgml @@ -24,73 +24,3 @@ modest-conf-keys - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/reference/tmpl/modest-conf.sgml b/docs/reference/tmpl/modest-conf.sgml index 7b6bb96..108e495 100644 --- a/docs/reference/tmpl/modest-conf.sgml +++ b/docs/reference/tmpl/modest-conf.sgml @@ -2,7 +2,7 @@ ModestConf - +Configuration system diff --git a/docs/reference/tmpl/modest-edit-window.sgml b/docs/reference/tmpl/modest-edit-window.sgml index 928e777..0ae938d 100644 --- a/docs/reference/tmpl/modest-edit-window.sgml +++ b/docs/reference/tmpl/modest-edit-window.sgml @@ -17,24 +17,3 @@ ModestEditWindow - - - - - -@parent: - - - - - - -@to: -@cc: -@bcc: -@subject: -@body: -@attachments: -@Returns: - - diff --git a/docs/reference/tmpl/modest-main-window.sgml b/docs/reference/tmpl/modest-main-window.sgml index f29e1ab..f3d5f71 100644 --- a/docs/reference/tmpl/modest-main-window.sgml +++ b/docs/reference/tmpl/modest-main-window.sgml @@ -29,8 +29,8 @@ ModestMainWindow -@modest_conf: -@modest_acc_mgr: +@factory: +@conf: @Returns: diff --git a/docs/reference/tmpl/modest-tny-header-tree-view.sgml b/docs/reference/tmpl/modest-tny-header-tree-view.sgml index ff18a4c..47587db 100644 --- a/docs/reference/tmpl/modest-tny-header-tree-view.sgml +++ b/docs/reference/tmpl/modest-tny-header-tree-view.sgml @@ -30,6 +30,8 @@ ModestTnyHeaderTreeView @folder: +@columns: +@style: @Returns: diff --git a/docs/reference/tmpl/modest-tny-transport-actions.sgml b/docs/reference/tmpl/modest-tny-transport-actions.sgml index c647d9f..37f0e83 100644 --- a/docs/reference/tmpl/modest-tny-transport-actions.sgml +++ b/docs/reference/tmpl/modest-tny-transport-actions.sgml @@ -45,6 +45,7 @@ ModestTnyTransportActions @bcc: @subject: @body: +@attachments_list: @Returns: diff --git a/docs/reference/tmpl/modest-ui.sgml b/docs/reference/tmpl/modest-ui.sgml index 75f3726..cde1434 100644 --- a/docs/reference/tmpl/modest-ui.sgml +++ b/docs/reference/tmpl/modest-ui.sgml @@ -2,7 +2,7 @@ ModestUI - +Abstraction for Modest user interfaces (GTK, Hildon, ...) @@ -42,18 +42,3 @@ ModestUI @Returns: - - - - - -@ui: -@to: -@cc: -@bcc: -@subject: -@body: -@att: -@Returns: - - diff --git a/docs/reference/tmpl/modest-unused.sgml b/docs/reference/tmpl/modest-unused.sgml index e69de29..73bd8d1 100644 --- a/docs/reference/tmpl/modest-unused.sgml +++ b/docs/reference/tmpl/modest-unused.sgml @@ -0,0 +1,264 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@parent: + + + + + + +@self: +@name: +@key: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@err: +@Returns: + + + + + + +@self: +@name: +@err: +@Returns: + + + + + + +@self: +@name: +@err: +@Returns: + + + + + + +@self: +@account_name: +@type: +@proto: +@only_enabled: +@Returns: + + + + + + +@self: +@name: +@key: +@val: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@val: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@val: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@val: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@val: +@err: +@Returns: + + + + + + +@self: +@name: +@key: +@val: +@err: +@Returns: + + + + + + +@to: +@cc: +@bcc: +@subject: +@body: +@attachments: +@Returns: + + + + + + +@ui: +@to: +@cc: +@bcc: +@subject: +@body: +@att: +@Returns: + -- 1.7.9.5