diff options
author | Chris Johns <chrisj@rtems.org> | 2020-09-01 12:09:41 +1000 |
---|---|---|
committer | Chris Johns <chrisj@rtems.org> | 2020-09-01 16:32:44 +1000 |
commit | 415b072babcf230af7fde2809cff1042db3ef48a (patch) | |
tree | d6c09335a8a6e17f47ed3bc55590efc01b67cf37 | |
parent | user: Change the BSP build set path (diff) | |
download | rtems-docs-415b072babcf230af7fde2809cff1042db3ef48a.tar.bz2 |
eng: Update the python template, add a shell template
-rw-r--r-- | eng/coding-file-hdr.rst | 63 |
1 files changed, 59 insertions, 4 deletions
diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst index cda631a..64eeec3 100644 --- a/eng/coding-file-hdr.rst +++ b/eng/coding-file-hdr.rst @@ -92,7 +92,7 @@ Use the following guidelines and template for C and C++ header files (here * Separate the Doxygen comment block from the copyright and license, so that the copyright and license information is not included in the Doxygen output. -* For C++ header files discard the extern "C". +* For C++ header files discard the ``extern "C"`` start and end sections. .. code-block:: c @@ -138,12 +138,14 @@ Use the following guidelines and template for C and C++ header files (here #include <foo/bar/xyz.h> + /* Remove for C++ code */ #ifdef __cplusplus extern "C" { #endif /* Declarations, defines, macros, inline functions, etc. */ + /* Remove for C++ code */ #ifdef __cplusplus } #endif @@ -207,13 +209,66 @@ and <COPYRIGHT HOLDER> placeholders see :ref:`FileHeaderCopyright`. Python File Template -------------------- -Use the following template for Python source files and other files which accept -a ``#``-style comment block. For the <FIRST YEAR>, <LAST YEAR>, and -<COPYRIGHT HOLDER> placeholders see :ref:`FileHeaderCopyright`. +Use the following template for Python source files. For the <FIRST YEAR>, +<LAST YEAR>, and <COPYRIGHT HOLDER> placeholders see +:ref:`FileHeaderCopyright`. + +The ``File documentation block`` is a `Python docstring (PEP 257) +<https://www.python.org/dev/peps/pep-0257/>`_ module documentation +block. RTEMS uses ``"""`` for Python docstrings. + +.. code-block:: python + + # SPDX-License-Identifier: BSD-2-Clause + """File documentation block""" + + # Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER> + # + # Redistribution and use in source and binary forms, with or without + # modification, are permitted provided that the following conditions + # are met: + # 1. Redistributions of source code must retain the above copyright + # notice, this list of conditions and the following disclaimer. + # 2. Redistributions in binary form must reproduce the above copyright + # notice, this list of conditions and the following disclaimer in the + # documentation and/or other materials provided with the distribution. + # + # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + # POSSIBILITY OF SUCH DAMAGE. + +If the Python source file is a command line command add the following as the +first line of the file: .. code-block:: python #!/usr/bin/env python + +A command line Python module does not need to have the ``.py`` file extension. + +Only specify ``python`` as the command to ``env``. A system that does not +provide the ``python`` command can install a virtual python environment or the +user can prepend the specific Python versioned command to the Python script on +the command line when invoking the command. + +Shell Scripts +------------- + +Use the following template for shell script source files and other files which +accept a ``#``-style comment block. For the <FIRST YEAR>, <LAST YEAR>, and +<COPYRIGHT HOLDER> placeholders see :ref:`FileHeaderCopyright`. + +.. code-block:: shell + + #!/bin/sh # SPDX-License-Identifier: BSD-2-Clause # File documentation block |