← Back to branch summary

~ubuntu-branches/ubuntu/maverick/gnash/maverick

« back to all changes in this revision

Viewing changes to doc/C/appendix.xml

  • Committer: Bazaar Package Importer
  • Author(s): Micah Gersten, Micah Gersten, Chris Coulson
  • Date: 2010-09-28 23:38:37 UTC
  • mfrom: (1.1.14 upstream) (3.1.9 sid)
  • Revision ID: james.westby@ubuntu.com-20100928233837-wcay0dodera1c7sz
Tags: 0.8.8-5ubuntu1
https://launchpad.net/bugs/636667
[ Micah Gersten <micahg@ubuntu.com> ]
* FFe - LP: #636667
* Merge from debian unstable.  Remaining changes:
  + Add Ubuntu flash alternatives in postinst and prerm
    - update debian/browser-plugin-gnash.postinst
    - update debian/browser-plugin-gnash.prerm

[ Chris Coulson <chris.coulson@canonical.com> ]
* Ensure the directories we are installing alternatives too exist
  already
  - add debian/browser-plugin-gnash.dirs

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/C/appendix.xml
1
 
<sect1 id="appendix">
2
 
  <title>Appendix</title>
3
 
  
4
 
  <sect2 id="codestyle">
5
 
    <title>Code Style</title>
6
 
 
7
 
    <para>
8
 
      I know any discussion of coding styles leads to strong opinions,
9
 
      so I'll state simply I follow the <ulink type="http"
10
 
      url="http://www.gnu.org/prep/standards/standards.html">GNU
11
 
      Coding Standards</ulink>. Where there is some flexibility as to
12
 
      the location of braces, I prefer mine on the end of a line when
13
 
      using an <emphasis>if</emphasis>, <emphasis>while</emphasis>, or <emphasis>do</emphasis>
14
 
      statement. I find this more compact style easier to read and
15
 
      parse by eye. I'm also a big fan of always using
16
 
      braces around <emphasis>if</emphasis> statements, even if they're one
17
 
      liners.
18
 
    </para>
19
 
 
20
 
    <para>
21
 
      Here's my tweaked style settings for <emphasis>Emacs</emphasis>, the one
22
 
      true editor to rule them all.
23
 
 
24
 
      <programlisting>
25
 
      (defconst my-style
26
 
          '((c-tab-always-indent   . t)
27
 
           (c-auto-newline         . t)
28
 
           (c-hanging-braces-alist . (
29
 
                                   (brace-list-intro)
30
 
                                   (namespace-open)
31
 
                                   (inline-open)
32
 
                                   (block-open)
33
 
                                   (brace-list-open)
34
 
                                   (brace-list-close)
35
 
                                   (brace-entry-open)
36
 
                                   (brace-else-brace)
37
 
                                   (brace-elseif-brace)
38
 
                                   (class-open after)
39
 
                                   (class-close)
40
 
                                   (defun-open after)
41
 
                                   (defun-close)
42
 
                                   (extern-lang-open)
43
 
                                   (inexpr-class-open)
44
 
                                   (statement-open)
45
 
                                   (substatement-open)
46
 
                                   (inexpr-class-close)))
47
 
            (c-hanging-colons-alist . ((member-init-intro before)
48
 
                                   (inher-intro)
49
 
                                   (case-label after)
50
 
                                   (label after)
51
 
                                   (access-label after)))
52
 
            (c-offsets-alist    . (
53
 
                                   (innamespace . 0)
54
 
                                   (case-label  . 2)
55
 
                                   ))
56
 
            (c-cleanup-list     . (
57
 
                                   (scope-operator)
58
 
                                   (empty-defun-braces)
59
 
                                   (brace-else-brace)
60
 
                                   (brace-elseif-brace)
61
 
                                   (defun-close-semi)
62
 
                                   (list-close-comma)
63
 
                                   )
64
 
                                )
65
 
    ;; no automatic newlines after ';' if following line non-blank or inside
66
 
    ;; one-line inline methods
67
 
    (add-to-list 'c-hanging-semi&amp;comma-criteria
68
 
                 'c-semi&amp;comma-no-newlines-before-nonblanks)
69
 
    (add-to-list 'c-hanging-semi&amp;comma-criteria
70
 
                 'c-semi&amp;comma-no-newlines-for-oneline-inliners)
71
 
;    (knr-argdecl-intro . -)
72
 
    (c-echo-syntactic-information-p . t)
73
 
    )
74
 
  "My GNU Programming Style")
75
 
    </programlisting>
76
 
 
77
 
    </para>
78
 
    
79
 
    <para>
80
 
      Another coding consideration: comments are good!  Over
81
 
      commenting isn't good.  Here is an over commented example:
82
 
 
83
 
      <programlisting>
84
 
        counter++;              // increment counter
85
 
      </programlisting>
86
 
      
87
 
      Gnash also uses <ulink type="http"
88
 
      url="http://www.doxygen.org">Doxygen</ulink> style
89
 
      comments. These are processed by Doxygen when building a cross
90
 
      reference of all the classes, and is a good way to help push
91
 
      internals documentation from the depths of the code into
92
 
      documentation where it can be seen by others.
93
 
    </para>
94
 
 
95
 
    <para>
96
 
      <emphasis>Doxygen</emphasis> style comments for <emphasis>C++</emphasis> code involves
97
 
      simply using three slashes <emphasis>///</emphasis> instead of the
98
 
      standard two slashes <emphasis>//</emphasis> used for C++
99
 
      comments. Here's a short comment block for the
100
 
      <emphasis>XML::cloneNode()</emphasis> method:
101
 
 
102
 
      <programlisting>
103
 
        /// \brief copy a node
104
 
        ///
105
 
        /// Method; constructs and returns a new XML node of the same type,
106
 
        /// name, value, and attributes as the specified XML object. If deep
107
 
        /// is set to true, all child nodes are recursively cloned, resulting
108
 
        /// in an exact copy of the original object's document tree.
109
 
        XMLNode &amp;
110
 
        XML::cloneNode(XMLNode &amp;newnode, bool deep) {
111
 
        ...
112
 
        }
113
 
      </programlisting> 
114
 
    </para>
115
 
    
116
 
    <para>
117
 
      The <emphasis>\brief</emphasis> keyword means that the 
118
 
      text becomes associated
119
 
      when listing all the classes on the generated web pages. The
120
 
      text after the blank line becomes the detailed description which
121
 
      appears on the generated web page for that class and method.
122
 
    </para>
123
 
  </sect2>
124
 
 
125
 
<!--
126
 
  <sect2 id="opcodes">
127
 
    <title>Shockwave Movie Opcodes</title>
128
 
 
129
 
    <sect3 id="v5">
130
 
      <title>Version 5</title>
131
 
      <para>
132
 
        FIXME:
133
 
      </para>
134
 
    </sect3>
135
 
    <sect3 id="v6">
136
 
      <title>Version 6</title>
137
 
      <para>
138
 
        FIXME:
139
 
      </para>
140
 
    </sect3>
141
 
    <sect3 id="v7">
142
 
      <title>Version 7</title>
143
 
      <para>
144
 
        FIXME:
145
 
      </para>
146
 
    </sect3>
147
 
    <sect3 id="v8">
148
 
      <title>Version 8</title>
149
 
      <para>
150
 
        FIXME:
151
 
      </para>
152
 
    </sect3>
153
 
    <sect3 id="v9">
154
 
      <title>Version 9</title>
155
 
      <para>
156
 
        FIXME:
157
 
      </para>
158
 
    </sect3>
159
 
 
160
 
  </sect2>
161
 
-->
162
 
 
163
 
</sect1>
164
 
 
165