.. include:: custom_tools.txt

.. _file sections:

*************
File Sections
*************

File Section Headings start at current indent level and end after column 75:

Major::

                                                                      column 75
                                                                              |
                                                                              v
    /**************************************************************************
     * Example Heading -- ALWAYS has at least 3 blank lines above it.
     * It isn't imperative that comment text be restricted to column 75, but it looks
     * nicer when it does.  The above line is an example which looks better when
     * wrapped before it extends beyond the space of the "block".  Sometimes this
     * is not practical though.
     ***************************************************************************/
                                                                              ^
                                                                              |
                                                                      column 75

Middle --- used only when an additional heading "level" is needed::

    /*=========================================================================
     * Example Heading -- ALWAYS has at least 2 blank lines above it.
     *=========================================================================*/

Minor --- common::

    /*-------------------------------------------------------------------------
     * Example Heading -- ALWAYS has at least 1 blank line above it.
     *-------------------------------------------------------------------------*/

    /* Common among lines of code.  This comment labels the code below it... */
    <some source code here>
        /* Whereas this indented comment labels the code above it. */

    /*------------------------- 28-Nov-2012 11:56 vw --------------------------
     * Timestamped Comment -- used for longer text that should stand out when
     * the modification time is pertinent, e.g. when long-standing source code
     * is undergoing a modification.
     *-------------------------------------------------------------------------*/

    /* 28-Nov-2012 11:56 vw
     * This is the format of a minor change were original source code should
     * be preserved.  This is used frequently in "delicate" source code and
     * is very useful when a team is working together on source code.
     *
     * Original code:
    BTN_WaitForUserToReleaseLeftButton();
    ++luiCurrMenuItem;
     */
    BTN_WaitForUserToReleaseRightButton();
    luiCurrMenuItem += 2;


    //{ 28-Nov-2012 12:02 vw
    // If needed, a modification can look like this also.
    // Original code:
    // <commented out source code here>
    <new source code here>
    //}

Re the above, keep in mind, this is used rarely since we try to stick with ANSI-standard C
code, and EOL comments aren't allowed in ANSI C.  :-(

Alternately, when compliance with ANSI C rules is important::

    /*{ 28-Nov-2012 12:02 vw
     * If needed, a modification can look like this also.
     * Original code:
    <commented out source code here>
     */
    <new source code here>
    /*}*/