|
1 | | -# NTIA/ITS Propagation Library Contribution Guide - Python |
| 1 | +# NTIA/ITS Propagation Library Contribution Guide |
2 | 2 |
|
3 | 3 | Thank you for your interest in contributing to this open source software. On this |
4 | 4 | page you will get an overview of the contribution workflow from opening an issue, |
@@ -210,8 +210,58 @@ double doubleTheInput(double x) |
210 | 210 |
|
211 | 211 | ### Python Wrappers |
212 | 212 |
|
| 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. |
213 | 220 |
|
| 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 | +``` |
214 | 236 |
|
215 | 237 | ### C#/.NET Wrappers |
216 | 238 |
|
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