MHKiT-MATLAB icon indicating copy to clipboard operation
MHKiT-MATLAB copied to clipboard

Feature: Fix and add test for incorrectly formatted docstrings

Open simmsa opened this issue 1 month ago • 1 comments

Status: Ready for Review

Add docstring validation python script and fix current issues with docstrings prevent sphinx from building the documentation:

The scripts/check_docstrings.py python script validates MATLAB function docstrings against the MHKiT-MATLAB docstring template to ensure proper Sphinx documentation generation. Docstrings are parsed by: https://github.com/sphinx-contrib/matlabdomain. This script checks for common issues that can cause Sphinx build failures or inconsistent documentation.

In this PR we also define a docstring template:

function result = descriptive_function_name(input_1, input_2, input_3)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Brief one-line description of what the function does
%
% Optional extended description paragraph. Can span multiple lines
% to provide additional context, mathematical background, data sources,
% or important behavioral notes about the function.
%
% Parameters
% ------------
% input_1 : type [units]
%   Description of first parameter. Can span multiple lines.
%   Additional details aligned with first line. Use two spaces for indentation
%     input_1.fieldname_1 : type [units]
%       Description of field
%     input_1.fieldname_2 : type [units]
%       Description of field
% input_2 : type [units]
%   Description of second parameter
% input_t : type [units] (optional)
%   Description of second parameter. Mark optional parameters
%   with (optional) after the type.
%
% Returns
% ---------
% output : type
%   Description of return value. For structure outputs,
%   document nested fields with indentation:
%     output.field1 : type [units]
%       Field 1 description
%     output.field2 : type [units]
%       Field description
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

arguments (Input)
    input_1 struct
    input_2 {mustBeInteger, mustBePositive}
    input_3 {mustBeInteger}
end

arguments (Output)
    result struct
end

% Function implementation goes here

end

This PR also add this template and other contribution details in a new CONTRIBUTING.md

simmsa avatar Nov 11 '25 15:11 simmsa

@hivanov-nrel, this is ready for review. This adds a docstring checker and defines a docstring template.

At this time it also made sense to just create a CONTRIBUTING.md with additional details on code development. Let me know if the docstring/function template makes sense, and if there is anything that makes sense to add or subtract.

simmsa avatar Nov 20 '25 16:11 simmsa