* some documentation updates
authorDirk-Jan C. Binnema <dirk-jan.binnema@nokia.com>
Mon, 17 Jul 2006 12:33:29 +0000 (12:33 +0000)
committerDirk-Jan C. Binnema <dirk-jan.binnema@nokia.com>
Mon, 17 Jul 2006 12:33:29 +0000 (12:33 +0000)
pmo-trunk-r389

docs/reference/modest-docs.sgml

index 0680e21..630da5b 100644 (file)
@@ -2,13 +2,18 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+
+  <copyright>
+  <year>2006</year>
+  <holder>Nokia Corporation</holder>
+  </copyright>
+
   <bookinfo>
-    <title>modest reference manual</title>
+    <title>modest technical documentation</title>
   </bookinfo>
 
   <preface>
     <title>Introduction</title>
-
     <para><application>modest</application> is a mail user agent
       (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
       <productname>Nokia 770 Internet Tablet</productname>. This document
        the <classname>ModestConf</classname>-class. It is declared
        in <filename> modest-conf.h</filename>, and
        the <systemitem>GConf</systemitem>-based implementation in 
-       <filename>modest-conf-gconf.c</filename>. As said, there could be
+       <filename>modest-conf.c</filename>. As said, there could be
        different implementations --
        nothing <systemitem>GConf</systemitem>-specific is visible in the
        <classname>ModestConf</classname>-<abbrev>API</abbrev>.
        Account Management is the part of <application>modest</application>
        that deals with the setting related to sending and receiving of
        e-mail. We will follow the libcamel-convention of using the
-       term <emphasis> store</emphasis> for an e-mail storage/retrieval
+       term <emphasis>store</emphasis> for an e-mail storage/retrieval
        server, and a <emphasis>transport</emphasis> for a server that
        transports mail to its destination.
       </para>
          </itemizedlist>
        </para>
        
-       <para>In the <filename>modest-proto.[ch]</filename> there are
-         various functions to check whether something is a valid protocol, and whether
-         it is a transport of a store.
+       <para>In <filename>modest-proto.[ch]</filename> there are various
+         functions to check whether something is a valid protocol, and
+         whether it is a transport of a store.
        </para>
        
        <para>Note that server accounts and accounts are relatively independent. While
       </sect1>
     </chapter>
 
-    <chapter>
-      <title>Finding the right transport</title>
+    <sec1>
+      <title>Account Management and Tinymail</title>
       <para>
-       One of the interesting topics in designing a mobile e-mail client is
-       to deal with transports (in
-       particular, <acronym>SMTP</acronym>). The reason for that is that
-       the majority of <acronym>SMTP</acronym>-servers only allow e-mail
-       from the same network. That means that for example <systemitem>
-       smtp.some-isp.com</systemitem> will only accept mail from
-       (<command>MAIL FROM:</command>) <systemitem>
-         user@some-isp.com</systemitem>, and refuse mail
-       from <systemitem>user@some-other-isp.com</systemitem>, unless the
-       recipient (<command>RCPT TO:</command>) is on the same network.
+       Tinymail needs the information about all configured accounts - and the
+       mechanism that it uses for that
+       is <interface>TnyAccountStoreIface</interface>. We don't want to use
+       the tinymail-provided <classname>TnyAccountStore</classname>, but
+       provide our own implementation
+       instead: <classname>ModestTnyAccountStore</classname>. This class
+       implements the <interface>TnyAccountStoreIface</interface>-interace in
+       terms of the aforementioned <classname>ModestAccountMgr</classname>.
       </para>
-    </chapter>
+      
+      <para>
+       One unexpected function
+       that  <classname>ModestTnyAccountStore</classname> needs to implement
+       is <symbol>tny¬†account_store¬†get_session</symbol> (to get the
+       Camel-session). This function must be provided as a public function,
+       with that exact name.
+      </para>
+    </sec1>
+  </chapter>
+  
+  
+  
+
+  <chapter>
+    <title>Finding the right transport</title>
+    <para>
+      One of the interesting topics in designing a mobile e-mail client is
+      to deal with transports (in
+      particular, <acronym>SMTP</acronym>). The reason for that is that
+      the majority of <acronym>SMTP</acronym>-servers only allow e-mail
+      from the same network. That means that for example <systemitem>
+       smtp.some-isp.com</systemitem> will only accept mail from
+      (<command>MAIL FROM:</command>) <systemitem>
+       user@some-isp.com</systemitem>, and refuse mail
+      from <systemitem>user@some-other-isp.com</systemitem>, unless the
+      recipient (<command>RCPT TO:</command>) is on the same network.
+    </para>
+  </chapter>
   </part>
   
+
+
   <chapter>
     <title>Coding guidelines</title>
     <para>
-      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 <emphasis>Linux CodingStyle guidelines</emphasis>
       (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
     </para>
       (setq indent-tabs-mode t)
       (setq c-basic-offset 8)
       </programlisting>
+      
+      Or the equivalent in your favourite editor.
     </para>
     
     <para>
-      Or the equivalent in your favourite editor.
+      Lines must not exceed 100 characters.
     </para>
-    
+
     <para>
-      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.
     </para>
       
+    <para>
+      Code should compile cleanly
+      with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
+      course this might not always be possible due to problems in dependent
+      libraries and/or compiler version. Therefore, do not
+      include <symbol>-Werror</symbol> in the standard compile options.
+    </para>
+
     <para>Global functions (the ones in <filename>.h</filename>-files) should
       be commented using
       <systemitem>gtk-doc</systemitem>.
     </para>
     
+    
+    
+
     <para>
        Furthermore, please follow 'conventional wisdom' for programming with 
        GLib/GTK+/GObject. Some things to remember: