Changes between Version 16 and Version 17 of coding_rules

Timestamp:

08/06/20 15:36:41 (5 years ago)

Author:

jdquinn

Comment:

Added documentation for Python doctrings

coding_rules

@@ -57 +57 @@
 bool Test(int a,double b,char* c){
 }}}
-== Matlab ==
+== MATLAB ==
 
-- All matlab routines should start with a help (Example and See Also are not mandatory):
+- All MATLAB routines should start with a help (Example and See Also are not mandatory):
 {{{
-#!m
+#!matlab
 function outputs=FunctionName(inputs)
 %FUNCTIONNAME - one line description
@@ -81 +81 @@
 
 {{{
-#!m
+#!matlab
 function outputs=hello()
 %HELLO - prints hello to the screen
@@ -102 +102 @@
 flake8  --ignore=E262,E265,F403,F405,E405,E501
 }}}
+
+=== Docstrings ===
+Adhering to [https://www.python.org/dev/peps/pep-0257/ PEP8 Docstring Conventions] while attempting to mirror the conventions we follow under MATLAB, modules, functions, classes, and method definitions should be documented according to the following protocol,
+
+{{{
+#!python
+def FunctionName(inputs):
+    """FUNCTIONNAME - one line description
+
+    Extensive description of what is being done, inputs
+    outputs, etc...
+
+    Usage:
+        outputs = FunctionName(inputs)
+
+    Example:
+        md.test = FunctionName(1)
+
+    See Also:
+        FunctionName2, FunctionName3, ...
+    """
+}}}
+
+As with MATLAB, at the very least, the first line and the 'Usage' should be provided. Unlike MATLAB, use indentations of 4 and 8 spaces.
 
 === MATLAB Built-In Equivalents ===