On 01/09/2020 04:10, chr...@rtems.org wrote:
From: Chris Johns <chr...@rtems.org>
---
eng/coding-file-hdr.rst | 62 ++++++++++++++++++++++++++++++++++++++---
1 file changed, 58 insertions(+), 4 deletions(-)
diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst
index cda631a..dafe82c 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,65 @@ 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 module documentation
Maybe add a link to:
https://www.python.org/dev/peps/pep-0257/
+block.
+
+.. code-block:: python
+
+ # SPDX-License-Identifier: BSD-2-Clause
+ '''File documentation block'''
All the examples in PEP 257 use """ strings. I used this style for all
the new Python code in rtems-central. Could we use """ instead of '''?
+
+ # 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
Python source file
+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.
Python module
+
+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
Python environment
+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:: python
+
+ # /bin/sh
#!/bin/sh
# SPDX-License-Identifier: BSD-2-Clause
# File documentation block
--
Sebastian Huber, embedded brains GmbH
Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone : +49 89 189 47 41-16
Fax : +49 89 189 47 41-09
E-Mail : sebastian.hu...@embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
