Extend source layout description in dev guide

[alexxy/gromacs.git] / docs / dev-manual / naming.rst

diff --git a/docs/dev-manual/naming.rst b/docs/dev-manual/naming.rst
index 5ae72cc0e3b7679dc877021fda95c0ea1e4ec843..987e19a80f307b835f667b446bdd6f9428f3ec40 100644 (file)
--- a/docs/dev-manual/naming.rst
+++ b/docs/dev-manual/naming.rst
@@ -12,12 +12,24 @@ attempt has been made to consolidate the naming.
 Files
 -----
 
-* Avoid having multiple files with the same name in different places within
-  the same library.  In addition to making things harder to find, C++ source
-  files with the same name can cause obscure problems with some compilers.
-  Currently, unit tests are an exception to the rule (there is only one
-  particular compiler that had problems with this, and a workaround is
-  possible if/when that starts to affect more than a few of the test files).
+* C++ source files have a ``.cpp`` extension, C source files ``.c``, and
+  headers for both use ``.h``.
+* For source file :file:`{file}.c`/:file:`{file}.cpp`, declarations that are
+  visible outside the source file should go into a correspondingly named
+  header: :file:`{file}.h`.  Some code may deviate from this rule to improve
+  readability and/or usability of the API, but this should then be clearly
+  documented.
+
+  There can also be a :file:`{file}-impl.h` file that declares classes or
+  functions that are not accessible outside the module.  If the whole file only
+  declares symbols internal to the module, then the :file:`-impl.h` suffix is
+  omitted.
+
+  In most cases, declarations that are not used outside a single source file
+  are in the source file.
+* Use suffix :file:`-doc.h` for files that contain only Doxygen documentation
+  for some module or such, for cases where there is no natural single header
+  for putting the documentation.
 * For C++ files, prefer naming the file the same as the (main) class it
   contains.  Currently all file names are all-lowercase, even though class
   names contain capital letters.
@@ -25,9 +37,12 @@ Files
   containing directory if that would cause unnecessary repetition (e.g., as a
   common prefix to every file name in the directory) and the remaining part of
   the name is unique enough.
-
-.. TODO: Copy/move relevant content from codelayout.rst here, and add
-   details.
+* Avoid having multiple files with the same name in different places within
+  the same library.  In addition to making things harder to find, C++ source
+  files with the same name can cause obscure problems with some compilers.
+  Currently, unit tests are an exception to the rule (there is only one
+  particular compiler that had problems with this, and a workaround is
+  possible if/when that starts to affect more than a few of the test files).
 
 .. TODO: Consider usage of underscores vs dashes in file names.