[rtems-docs commit] coding-naming: Convert TBD to Rest format (GCI 2018)

Joel Sherrill joel at rtems.org
Tue Dec 18 17:22:24 UTC 2018

Module:    rtems-docs
Branch:    master
Commit:    edde29e203fbdd2cbf22abb1bf667d069786af14
Changeset: http://git.rtems.org/rtems-docs/commit/?id=edde29e203fbdd2cbf22abb1bf667d069786af14

Author:    Pritish Jain <pritishjain2001 at gmail.com>
Date:      Tue Dec  4 05:28:47 2018 +0530

coding-naming: Convert TBD to Rest format (GCI 2018)


 eng/coding-naming.rst | 87 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 85 insertions(+), 2 deletions(-)

diff --git a/eng/coding-naming.rst b/eng/coding-naming.rst
index 054dd5d..4fb4e7c 100644
--- a/eng/coding-naming.rst
+++ b/eng/coding-naming.rst
@@ -6,5 +6,88 @@
 Naming Rules
-TBD  - Convert the following to Rest and insert into this file
-TBD  - https://devel.rtems.org/wiki/Developer/Coding/NamingRules
+.. COMMENT:TBD  - Convert the following to Rest and insert into this file
+.. COMMENT:TBD  - https://devel.rtems.org/wiki/Developer/Coding/NamingRules
+General Rules
+ *  Avoid abbreviations.
+    *  Exception: when the abbreviation is more common than the full word.
+    *  Exception: For well-known acronyms.
+ *  Use descriptive language.
+ *  File names should be lower-case alphabet letters only, plus the extension.
+    Avoid symbols in file names.
+ *  Prefer to use underscores to separate words, rather than
+    `CamelCase <https://devel.rtems.org/wiki/CamelCase>`_.or !TitleCase.
+ *  Local-scope variable names are all lower case with underscores between words.
+ *  CPP macros are all capital letters with underscores between words.
+ *  Enumerated (enum) values are all capital letters with underscores between
+    words, but the type name follows the regular rules of other type names.
+ *  Constant (const) variables follow the same rules as other variables.
+    An exception is that a const that replaces a CPP macro might be all
+    capital letters for backward compatibility.
+ *  Type names, function names, and global scope names have different rules
+    depending on whether they are part of the public API or are internal
+    to RTEMS, see below.
+**User-Facing APIs**
+The public API routines follow a standard API like POSIX or BSD or start
+with *rtems_*. If a name starts with *rtems_*, then it should be assumed to be
+available for use by the application and be documented in the User's Guide.
+If the method is intended to be private, then make it static to a file or
+start the name with a leading _.
+**Classic API**
+* Public facing APIs start with *rtems_* followed by a word or phrase to
+  indicate the Manager or functional category the method or data type
+  belongs to.
+* Non-public APIs should be static or begin with a leading _. The required
+  form is the use of a leading underscore, functional area with leading
+  capital letter, an underscore, and the method with a leading capital letter.
+ *  Follow the rules of POSIX.
+**RTEMS Internal Interfaces**
+**Super Core**
+The `Super Core <https://docs.rtems.org/doxygen/cpukit/html/>`_. is organized in an
+Object-Oriented fashion. Each score Handler is a Package, or Module,
+and each Module contains type definitions, functions, etc.
+The following summarizes our conventions for using names within
+`SuperCore <https://docs.rtems.org/doxygen/cpukit/html/>`_. Modules.
+ *  Use "Module_name_Particular_type_name" for type names.
+ *  Use "_Module_name_Particular_function_name" for functions names.
+ *  Use "_Module_name_Global_or_file_scope_variable_name" for global or
+    file scope variable names.
+Within a structure:
+ *  Use "Name" for struct aggregate members.
+ *  Use "name" for reference members.
+ *  Use "name" for primitive type members.
+As shown in the following example:
+   .. code-block:: c
+       typedef struct {
+           Other_module_Struct_type    Aggregate_member_name;
+           Other_module_Struct_type   *reference_member_name;
+           Other_module_Primitive_type primitive_member_name;
+         } The_module_Type_name;
+ * TODO.

More information about the vc mailing list