# Appendix

## Code Style

I know any discussion of coding styles leads to strong opinions, so I'll state simply I follow the GNU Coding Standards. Where there is some flexibility as to the location of braces, I prefer mine on the end of a line when using an `if`, `while`, or `do` statement. I find this more compact style easier to read and parse by eye. I'm also a big fan of always using braces around `if` statements, even if they're one liners.

Here's my tweaked style settings for `Emacs`, the one true editor to rule them all.

          (defconst my-style
              '((c-tab-always-indent   . t)
               (c-auto-newline	   . t)
               (c-hanging-braces-alist . (
    				   (brace-list-intro)
    				   (namespace-open)
    				   (inline-open)
    				   (block-open)
    				   (brace-list-open)
    				   (brace-list-close)
    				   (brace-entry-open)
    				   (brace-else-brace)
    				   (brace-elseif-brace)
    				   (class-open after)
    				   (class-close)
    				   (defun-open after)
    				   (defun-close)
    				   (extern-lang-open)
    				   (inexpr-class-open)
    				   (statement-open)
    				   (substatement-open)
    				   (inexpr-class-close)))
                (c-hanging-colons-alist . ((member-init-intro before)
                                       (inher-intro)
                                       (case-label after)
                                       (label after)
                                       (access-label after)))
                (c-offsets-alist	. (
    				   (innamespace . 0)
                                       (case-label  . 2)
    				   ))
                (c-cleanup-list	. (
    				   (scope-operator)
    				   (empty-defun-braces)
    				   (brace-else-brace)
    				   (brace-elseif-brace)
    				   (defun-close-semi)
    				   (list-close-comma)
    				   )
    				)
        ;; no automatic newlines after ';' if following line non-blank or inside
        ;; one-line inline methods
        (add-to-list 'c-hanging-semi&comma-criteria
    		 'c-semi&comma-no-newlines-before-nonblanks)
        (add-to-list 'c-hanging-semi&comma-criteria
    		 'c-semi&comma-no-newlines-for-oneline-inliners)
    ;    (knr-argdecl-intro . -)
        (c-echo-syntactic-information-p . t)
        )
      "My GNU Programming Style")

Other coding considerations are comments are good! Over commenting isn't good, as some things like:

    	counter++;		// increment counter

Gnash also uses Doxygen. style comments. These get processed by Doxygen when building a cross reference of all the classes, and is a good way to help push internals documentation from the depths of the code into documentation where it can be seen by others.

`Doxygen` style comments for `C++` code is simply using three slashes `///` instead of the standard two slashes `//` used for C++ comments. Here's a short comment block for the `XML::cloneNode()` method:

    	/// \brief copy a node
    	///
    	/// Method; constructs and returns a new XML node of the same type,
    	/// name, value, and attributes as the specified XML object. If deep
    	/// is set to true, all child nodes are recursively cloned, resulting
    	/// in an exact copy of the original object's document tree.
    	XMLNode &
    	XML::cloneNode(XMLNode &newnode, bool deep) {
    	...
    	}

The `\brief` keyword has that text get associated when listing all the classes on the generated web pages. The text after the blank link becomes the detailed description that is on the generated web page for that class and method.

&amf;