Start with templates for the application configuration options. Remove "Format to be followed for making changes in this file" from c-user.
Update #3910. --- c-user/config/intro.rst | 44 --------------------------- eng/doc-guide.rst | 79 +++++++++++++++++++++++++++++++++++++++++++++++++ eng/management.rst | 1 + 3 files changed, 80 insertions(+), 44 deletions(-) create mode 100644 eng/doc-guide.rst diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst index 46267d7..4c2f715 100644 --- a/c-user/config/intro.rst +++ b/c-user/config/intro.rst @@ -151,50 +151,6 @@ In general, ``<rtems/confdefs.h>`` is very accurate when given enough information. However, it is quite easy to use a library and forget to account for its resources. -Format to be followed for making changes in this file -===================================================== - -MACRO NAME: - Should be alphanumeric. Can have '_' (underscore). - -DATA TYPE: - Please refer to all existing formats. - -RANGE: - The range depends on the Data Type of the macro. - - - If the data type is of type task priority, then its value should be an - integer in the range of 1 to 255. - - - If the data type is an integer, then it can have numbers, characters (in - case the value is defined using another macro) and arithmetic operations - (+, -, \*, /). - - - If the data type is a function pointer the first character should be an - alphabet or an underscore. The rest of the string can be alphanumeric. - - - If the data type is RTEMS Attributes or RTEMS Mode then the string should - be alphanumeric. - - - If the data type is RTEMS NAME then the value should be an integer>=0 or - ``RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' )`` - -DEFAULT VALUE: - The default value should be in the following formats- Please note that the - '.' (full stop) is necessary. - - - In case the value is not defined then: This is not defined by default. - - - If we know the default value then: The default value is XXX. - - - If the default value is BSP Specific then: This option is BSP specific. - -DESCRIPTION: - The description of the macro. (No specific format) - -NOTES: - Any further notes. (No specific format) - Configuration Example ===================== diff --git a/eng/doc-guide.rst b/eng/doc-guide.rst new file mode 100644 index 0000000..cdcd04f --- /dev/null +++ b/eng/doc-guide.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + +.. _DocGuide: + +Documentation Guidelines +************************ + +Application Configuration Options +================================= + +Add at least an index entry and a label for the configuration option. Use a +pattern of ``CONFIGURE_[A-Z0-9_]+`` for the option name. Use the following +template for application configuration feature options: + +.. code-block:: rst + + .. index:: CONFIGURE_FEATURE + + .. _CONFIGURE_FEATURE: + + CONFIGURE_FEATURE + ----------------- + + CONSTANT: + ``CONFIGURE_FEATURE`` + + OPTION TYPE: + This configuration option is a boolean feature define. + + DEFAULT CONFIGURATION: + If this configuration option is undefined, then the described feature is not + enabled. + + DESCRIPTION: + In case this configuration option is defined, then feature happens. + + NOTES: + Keep the description short. Add all special cases, usage notes, error + conditions, configuration dependencies, references, etc. here to the notes. + +Use the following template for application configuration integer and +initializer options: + +.. code-block:: rst + + .. index:: CONFIGURE_VALUE + + .. _CONFIGURE_VALUE: + + CONFIGURE_VALUE + ----------------- + + CONSTANT: + ``CONFIGURE_VALUE`` + + OPTION TYPE: + This configuration option is an integer (or initializer) define. + + DEFAULT VALUE: + The default value is X. + + VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to A. + + * It shall be less than or equal to B. + + * It shall meet C. + + DESCRIPTION: + The value of this configuration option defines the Y of Z in W. + + NOTES: + Keep the description short. Add all special cases, usage notes, error + conditions, configuration dependencies, references, etc. here to the notes. diff --git a/eng/management.rst b/eng/management.rst index 6eb4217..6a8e057 100644 --- a/eng/management.rst +++ b/eng/management.rst @@ -16,6 +16,7 @@ Software Development Management vc-users vc-authors coding + doc-guide python-devel change-management issue-tracking -- 2.16.4 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
