Skip to content

Commit 0a5dc89

Browse files
Update CONTRIBUTING.md
1 parent a5bbfec commit 0a5dc89

File tree

1 file changed

+52
-2
lines changed

1 file changed

+52
-2
lines changed

CONTRIBUTING.md

Lines changed: 52 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# NTIA/ITS Propagation Library Contribution Guide - Python
1+
# NTIA/ITS Propagation Library Contribution Guide
22

33
Thank you for your interest in contributing to this open source software. On this
44
page you will get an overview of the contribution workflow from opening an issue,
@@ -210,8 +210,58 @@ double doubleTheInput(double x)
210210
211211
### Python Wrappers
212212
213+
The Python wrapper code is documented in the [Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)
214+
format. It is recommended to include docstrings for all primary functions, classes,
215+
or structures provided by the Python wrapper. Further, function signatures should
216+
include [type annotation](https://docs.python.org/3/library/typing.html) for inputs
217+
and returned values. Inline or other comments should be included to explain other
218+
variables or functionalities of the code. Below is an example showing the recommended
219+
documentation format.
213220
221+
```python
222+
223+
CONSTANT_EXPOSED_BY_MODULE = 42 # A brief comment could explain what this is
224+
225+
def double_the_input(x: float) -> float:
226+
"""This is a brief description of the function.
227+
228+
This is an optional, longer description of the function.
229+
It can span multiple lines.
230+
231+
:param x: The input value, and its expected units.
232+
:return: The result y = 2*x
233+
"""
234+
return 2 * x
235+
```
214236

215237
### C#/.NET Wrappers
216238

217-
### MATLAB Wrappers
239+
In C#/.NET, documentation comments are written in XML format and are used to
240+
generate documentation through tools like Visual Studio. Use `<summary>` tags to
241+
provide brief descriptions of classes, constants, functions, etc. Functions should
242+
include `<param>` and `<returns>` elements for all inputs and outputs. An example
243+
of this documentation style is shown below.
244+
245+
```csharp
246+
/// <summary>
247+
/// Represents a class that contains constants and methods related to calculations.
248+
/// </summary>
249+
public class CalculationUtils
250+
{
251+
/// <summary>
252+
/// A constant value exposed by the module.
253+
/// </summary>
254+
public const int CONSTANT_EXPOSED_BY_MODULE = 42;
255+
256+
/// <summary>
257+
/// Doubles the input value.
258+
/// </summary>
259+
/// <param name="x">The input value to be doubled.</param>
260+
/// <returns>The doubled value of the input.</returns>
261+
public double DoubleTheInput(double x)
262+
{
263+
// Brief comment explaining what this function does.
264+
return 2 * x;
265+
}
266+
}
267+
```

0 commit comments

Comments
 (0)