Function Header + Code Documentation

[JOlucak]

We should think about adding function headers similar to e.g. sosopt or other toolboxes. Even if we move to another language the header can be moved, too.
The header should include a short description, input, output, if necessary reference (to papers,books etc), license related things and maybe a change record. In sosopt short examples with different in- and outputs are also provided. I provide an example below.

We should also think about code documention using doxygen https://www.doxygen.nl/
There is also a Matlab tool on the exchange that allows us to use Doxygen syntax https://de.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab

If we move to C/C++ we probably only have to exchange the comment indicator i.e. from % to //.

[JOlucak]

Example Header Function (only example not fully with Doxygen syntax):

% ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
%> @brief This is a short decription.
%>-----------------------------------------------------------------
%> Input:
%> input_a- This is the first input [unit]
%> input_b- This is the second input [unit]
%>-----------------------------------------------------------------
%> Output:
%> output_a- This is the only output [unit].
%>-----------------------------------------------------------------
%>References:
%>[1]-Name, First Name - Title, Year etc.
%>[2]-Name, First Name - Title, Year etc.
%>-----------------------------------------------------------------
%>Licencse: License text etc.
%>-----------------------------------------------------------------
%> Changes:
%> 1.1.2024- Initial function
%> 2.1.2024-Change 1
%> 3.1.2024-Change 2
%>-----------------------------------------------------------------
%> Example Usage:
%> input_a = 1;
%> input_b = 2;
%>[output_a] = niceFunction(input_a,input_b);

% ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

function [output_a] = niceFunction(input_a,input_b)

end

[JOlucak]

Example Header for examples or demo (only example not fully with Doxygen syntax):

% ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
%> @brief This is a short decription.
%>-----------------------------------------------------------------
%>References:
%>[1]-Name, First Name - Title, Year etc.
%>-----------------------------------------------------------------
%>Licencse: License text etc.
% ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

[tcunis]

Having a change log in the header defeats the purpose of git, especially in this early stages of development.

[tcunis]

I don't like having lines comments that are just random symbols. It makes the files look cluttered.

[tcunis]

Every file should start with a comment

%FILENAME Short description of script, function, or class.

to show up in the MATLAB file browser.

[Fabian-Geyer]

Update:
There are several ways to document Matlab code. The following could be good choices:

1. Generic Matlab Help using comments only
2. Generic Matlab Help using comments + HTML (see Matlab Custom Documentation)
3. Using Sphinx with the matlabdomain extension
4. Sphinx + matlabdomain extension + matlabdoc builder

Only using Matlab comments is the most simple solution. The documentation can then be accessed with

doc casos.PS

or

help casos.PS

from the Matlab command line.
Adding the files required for an official Matlab project would be the "official" way to do it.

However, using Sphinx allows for even more flexibility as one can combine automatic extraction of classes/functions/methods with custom additional information in the .rst format. This even allows using Latex expressions.

The matlabdoc builder seems to be a good way to automatically turn the Sphinx documentation into the official Matlab html documentation format from 2.

3. is currently being worked on in the branch https://github.com/iFR-ACSO/casos/tree/documentation-sphinx

Some example Screenshots:

[tcunis]

Would it be possible to distinguish the documentation between the external and internal API (like CasADi does)? Otherwise, if someone just wants to 'use' the toolbox, they might be overwhelmed by all the internal documentation...

[Fabian-Geyer]

After trying this, it seems like it will not work in an automated fashion. However, we can exclude methods, meaning for the most important interfaces, the documentation would require some manual work. Here is an example of what it looks like to exclude members:

.. autoclass:: PS
   :members:
   :exclude-members: casadi.SX, casadi.DM

However, there could be other ways to achieve this that I am not aware of yet.
Also, one could add a folder structure where the internal methods are separate from the API for users by adding different files.

Personally, I think it would be beneficial to add some guides for using

• sossol
• qcsossol
• sdpsol
• conic
• casos.PS / casos.PS.sym
  extending the README.md. Examples could also be added. That would require some manual labour anyways.

[tcunis]

Also, one could add a folder structure where the internal methods are separate from the API for users by adding different files.

This already exists -- everything within the +package subpackages is considered internal, as are all methods which are not public (that's OO in a nutshell ;-) ).

[Fabian-Geyer]

Yes, seperating those is easily possible 👍