doc - expand style conventions in dev docs

Author: jeremylt

doc/sphinx/source/libCEEDdev.md

@@ -201,8 +201,66 @@ In addition to those automatically enforced style rules, libCEED tends to follow
 - Type names: `PascalCase` or language specific style
 - Constant names: `CAPS_SNAKE_CASE` or language specific style
 
+In general, variable and function names should avoid abbreviations and err on the side of verbosity to improve readability.
+
 Also, documentation files should have one sentence per line to help make git diffs clearer and less disruptive.
 
+## Function Conventions
+
+### Naming
+All functions in the libCEED library should be prefixed by `Ceed` and generally take a `Ceed` object as its first argument.
+If a function takes, for example, a `CeedOperator` as its first argument, then it should be prefixed with `CeedOperator`.
+
+### Style
+Functions should adhere mostly to the PETSc function style, specifically:
+
+1. All local variables of a particular type (for example, `CeedInt`) should be listed on the same line if possible; otherwise, they should be listed on adjacent lines. For example,
+```c
+// Correct
+CeedInt   a, b, c;
+CeedInt  *d, *e;
+CeedInt **f;
+
+// Incorrect
+CeedInt a, b, c, *d, *e, **f;
+```
+  
+2. Local variables should be initialized in their declaration when possible.
+3. Nearly all functions should have a return type of `int` and return a `CeedErrorType` to allow for error checking.
+4. All functions must start with a single blank line after the local variable declarations.
+5. All libCEED function calls must have their return value checked for errors using the `CeedCall()` or `CeedCallBackend()` macro.
+   This should be wrapped around the function in question.
+6. In libCEED functions, variables must be declared at the beginning of the code block (C90 style), never mixed in with code.
+   However, when variables are only used in a limited scope, it is encouraged to declare them in that scope.
+7. Do not put a blank line immediately blank line immediately before `return CEED_ERROR_SUCCESS;`.
+8. All libCEED functions must use Doxygen comment blocks before their *definition* (not declaration).
+   The block should begin with `/**` and end with `**/`, each on their own line.
+   The block should be indented by two spaces and should contain an `@brief` tag and description, a newline, a line stating whether the function is collective, a  newline, `@param` tags for each parameter, a newline, and a `@return` line formatted exactly as in the example below.
+   All parameter lines in the Doxygen block should be formatted such that parameter names and descriptions are aligned.
+   There should be a exactly one space between `@param[dir]` (where `dir` is `in`, `out`, or `in,out`) and the parameter name for the closest pair, as well as  between the parameter name and description.
+    For example:
+```c
+/**
+  @brief Initialize a `Ceed` context to use the specified resource.
+
+  Note: Prefixing the resource with "help:" (e.g. "help:/cpu/self") will result in @ref CeedInt() printing the current libCEED version number and a list of current available backend resources to `stderr`.
+
+  @param[in]  resource Resource to use, e.g., "/cpu/self"
+  @param[out] ceed     The library context
+
+  @return An error code: 0 - success, otherwise - failure
+
+  @ref User
+
+  @sa CeedRegister() CeedDestroy()
+**/
+int CeedInit(const char *resource, Ceed *ceed) {
+```
+9. Function declarations should include parameter names, which must exactly match those in the function definition.
+10. External functions, i.e. those used in tests or examples, must have their *declarations* prefixed with `CEED_EXTERN`.
+    All other functions should have their *declarations* prefixed with `CEED_INTERN`.
+    Function *definitions* should have neither.
+
 ## Clang-tidy
 
 Please check your code for common issues by running