Correct some typos. Add IDs to headings. Add some hints about commenting.

docs/lcdproc-dev/add-your-driver.docbook

@@ -19,6 +19,11 @@ Be sure to read <xref linkend="programming"/> and <xref linkend="driver-api"/>
 as well.
 </para>
 
+<para>
+As a starting point you may take a look at the debug driver. It is available
+as <filename>server/drivers/debug.c</filename>.
+</para>
+
 </sect1>
 
 
@@ -32,7 +37,7 @@ driver to be included in LCDproc's code some conditions have to be met:</para>
 <orderedlist>
 <listitem>
   <para>The hardware (display or enclosing product) is publicly sold
-  <emphasis>OR</emphasis> the schematics and firmware (if required) are publicy
+  <emphasis>OR</emphasis> the schematics and firmware (if required) are publicly
   available.
     <footnote><para>Therefore I will not commit drivers for displays ripped out
     from an old telephone for your private hardware project and are not
@@ -47,27 +52,27 @@ driver to be included in LCDproc's code some conditions have to be met:</para>
   <para>The submitter is or is acting on behalf of the original driver
   developer.
     <footnote><para>I will not submit drivers found somewhere on the internet and
-    submitted without the original developer's acknowledgement.</para></footnote>
+    submitted without the original developer's written acknowledgement.</para></footnote>
   </para>
 </listitem>
 <listitem>
-  <para>The driver describtion contains a valid email address for contacting
+  <para>The driver description contains a valid email address for contacting
   the submitter or developer.</para>
 </listitem>
 <listitem>
   <para>The code is commented <emphasis>AND</emphasis> includes appropriate
-  Doxygen comments, especially for private / non-API functions.</para>
+  Doxygen comments, especially for internal / non-API functions.</para>
 </listitem>
 <listitem>
   <para>End user documentation (updates to man pages <emphasis>AND</emphasis>
-  user-guide in docbook) is available.</para>
+  User's Guide in docbook format) is available.</para>
 </listitem>
 <listitem>
   <para>Driver options are described in the end user documentation
   <emphasis>AND</emphasis> <filename>LCDd.conf</filename>.</para>
 </listitem>
 <listitem>
-  <para>The driver adhere the style guide as described in <xref linkend="code-style"/>.</para>
+  <para>The driver adheres to the style guide as described in <xref linkend="code-style"/>.</para>
 </listitem>
 </orderedlist>
 
@@ -271,6 +276,34 @@ Please do not forget to also add the required documentation,
 so that your driver can be used from others as well.
 </para>
 
+<sect2 id="documentation-source">
+<title>Within the source code</title>
+
+<para>
+We use Doxygen to document functions and data types. The doxygen documentation
+can be created anytime by changing to the <filename>docs/</filename> directory
+and running <command>doxygen</command>.
+</para>
+<para>
+When documenting your driver's API functions you may use a short hand version
+and add 'API:' to the beginning of your comment and leave out the parameter
+and return value description (as we know what the API is doing). If you use
+some clever algorithm inside a function please add a few words about it.
+</para>
+<note>
+<para>
+Always document functions internal to the driver! We do know what the API
+does (or is expected to do) but we don't know about what your driver does
+internally.
+</para>
+<para>
+Read <xref linkend="code-style-comments"/> on how for format comments.
+</para>
+</note>
+
+</sect2>
+
+
 <sect2 id="documentation-LCDd.conf">
 <title>The configuration file, LCDd.conf</title>
 

docs/lcdproc-dev/make-driver.docbook

@@ -21,9 +21,9 @@ dedicated chapter in this book.
 <title>port.h : Parallel port I/O</title>
 
 <para>
-The file port.h, located in the server/drivers/ directory provide Input/Output
-and port permissions for the PC compatible parallel port, also known as the
-LPT port.
+The file <filename>port.h</filename>, located in the <filename>server/drivers/</filename>
+directory provide Input/Output and port permissions for the PC compatible
+parallel port, also known as the LPT port.
 </para>
 
 <para>
@@ -32,7 +32,15 @@ has parallel port! In these situations, the configure script will see this and
 disable drivers that need a parallel port.
 </para>
 
-<para>port.h file defines 6 static inline functions for port I/O:</para>
+<para>
+The functions in <filename>port.h</filename> are defined and as 'static inline'.
+Therefore each driver including this header file gets its own copy of the
+functions and they are inlined into the driver's code.  As a result calls to
+port_in() and port_out() are directly translated to inb() or outb() or
+assembly code by the compiler. There is less to no overhead in using them.
+</para>
+
+<para><filename>port.h</filename> file defines 6 static inline functions for port I/O:</para>
 
 <sect3 id="port-in">
 <title>Read a byte from port</title>
@@ -130,23 +138,24 @@ disable drivers that need a parallel port.
 <screen>
 #include "port.h"
 
-/* Get access to these 3 ports:
-    0x378 (CONTROL),
-    0x379 (STATUS) and
-    0x37A (DATA)
-*/
-if ( -1 == port_access_multiple(0x378,3) ) {
+/*
+ * Get access to these 3 ports:
+ *  0x378 (CONTROL),
+ *  0x379 (STATUS) and
+ *  0x37A (DATA)
+ */
+if (port_access_multiple(0x378, 3) == -1) {
 	/* Access denied, do something */
 }
 
 /* Write a 'A' to the control port */
-ort_out(0x378, 'A');
+port_out(0x378, 'A');
 
 /* Read from the status port */
 char status = port_in(0x379);
 
 /* Close the 3 ports */
-port_deny_multiple(0x378,3);
+port_deny_multiple(0x378, 3);
 </screen>
 
 </sect3>

docs/lcdproc-dev/programming.docbook

@@ -114,7 +114,7 @@ should look like.
   </para>
 </note>
 
-<sect2>
+<sect2 id="code-style-indention">
 <title>File format and indention</title>
 <itemizedlist mark="opencircle">
   <listitem>
@@ -140,7 +140,7 @@ should look like.
     <para>
     <emphasis>Indention: </emphasis>Tab indention shall be used (with tab
     width set to 8 characters). Only exception are switch labels which are
-    indented a half tab (4 characters).
+    indented a half tab (4 spaces).
     </para>
   </listitem>
   <listitem>
@@ -153,14 +153,15 @@ should look like.
 </itemizedlist>
 </sect2>
 
-<sect2>
+<sect2 id="code-style-naming">
 <title>Naming conventions</title>
 <itemizedlist mark="opencircle">
   <listitem>
     <para>
     <emphasis>Function names:</emphasis>
-    Function names shall be lowercase. We do not use CamelCase. Multiple words
-    are separated by underscore.
+    Function names shall be lowercase. We do not use CamelCase (some
+    historical exceptions may exist). Multiple words are separated by
+    underscore.
     </para>
   </listitem>
   <listitem>
@@ -198,7 +199,7 @@ unsigned char HD44780_scankeypad(PrivateData *p);
 </example>
 </sect2>
 
-<sect2>
+<sect2 id="code-style-comments">
 <title>Comments</title>
 <itemizedlist mark="opencircle">
   <listitem>
@@ -248,7 +249,7 @@ unsigned char HD44780_scankeypad(PrivateData *p);
 </itemizedlist>
 </sect2>
 
-<sect2>
+<sect2 id="code-style-statements">
 <title>Statement style</title>
 <itemizedlist mark="opencircle">
   <listitem>
@@ -309,7 +310,7 @@ y--;
   <listitem>
     <para><emphasis>Function calls:</emphasis></para>
     <para>
-    There shall be no space between the function call and the opening '(' of
+    There shall be no space between the function call and the opening brace '(' of
     the parameter list. Within the parameter list a space shall be after each
     parameter.
     </para>