3. Documentation Guidelines
Developers of eMach should read this document to understand expectations of the documentation files related to any code contributed to the eMach
codebase. This document outlines the requirements for the documentation sections related to analyzers
and machine_designs
.
3.1. Analyzer Documentation
Each analyzer within the eMach
codebase must be summarized such that someone with a basic understanding of electric machines can understand the
purpose and structure of the analyzer. The documentation files devoted to each analyzer must contain the following sections:
Model Background
Inputs from User
Outputs to User
3.1.1. Model Background
Provide information to explain the motivation, application, and any other knowledge required to understand where and how the analyzer can be applied. This can be in the form of equations, images, descriptions, and references to publications or other analyzers. Any assumptions that are made must be explained.
3.1.2. Input from User
Detail the required inputs to the problem and analyzer classes. This must include a table with the following three columns:
Argument
Description
Units
Separate tables should be provided for the initializer of the problem class and the analyzer class (if the analyzer class has an initializer).
A copy-paste example code block must be included after the table that illustrates the necessary includes, creating a problem object, and creating an analyzer object.
3.1.3. Output to User
Describe the attributes and functions of the analyzer’s results class. This must be done using a table with the following three columns:
Attribute/function name
Description
Units
If a row is describing a function, the description column should be used to describe the function’s arguments and their units.
The Units
column is intended to describe the units of the function’s return value.
Results classes that have properties/functions that return more complicated objects can make use of multiple tables to effectively describe their functionality.
A copy-paste example code block must be included that completes the example code block provided in Input from User
by calling the analyze()
function and rendering the return values. It is recommended to include post-processing code (such as creating a plot) to further illustrate the use of the output data.