summaryrefslogtreecommitdiffstats
path: root/eng/doc-guide.rst
blob: cdcd04f3725b9e8dbb8ab45d1334b6668bb10acf (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
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.