[pre-wip] document the API.

[Lucarda]

in pure-data/pure-data#1549 (comment) @Spacechild1 said:

Sure. This just shows again how important it is to document an API

May be this can be included in the #35 "still in pre-alpha draft" project.

[Spacechild1]

When I mentioned documenting the public API, I rather thought of using Doxygen comments. Of course, with doxygen you can automatically generate HTML documentation and that could be hosted on puredata.info.

[umlaeute]

i agree that having a literate programming documentation (e.g. using Doxygen; but even unstructured comments would already help) would be much more useful than having an independent document.

[danomatika]

I've added (light) Doxyen commenting to the modules I've written or updated. A big help would be to add such to m_pd.h. So far I prefer a terser form to keep readability in the headers themselves.

UPDATE:

Examples:

• z_libpd.h
• s_net.h
• d_soundfile.h

z_libpd.h uses /// while the others use /** & */ pairs to better match Miller's commenting style. In other open source projects, I tend to also use the Oxygen-specific \brief, \class, and \return tags at a minimum. The next step up would be to use \param for each function parameter, but I find that tends to get wordy quickly.

Also, so far here I use informal section headers ala /* sending messages to pd */ but this could also be expanded for Doxygen's \section tag ala /* \section Sending Messages to Pd */

UPDATE2:

My experience pushing for internal documentation in OpenFrameworks also leads to not adopting an overly-pendantic or full-fledged style as A. most people won't bother themselves to follow it and B. if it looks hard most people won't bother to write documentation at all. This is still an ongoing problem with oF. :( It has to be a part of the process and not something forced later on, at least with any new code or code refactor processes.

[Spacechild1]

My experience pushing for internal documentation in OpenFrameworks also leads to not adopting an overly-pendantic or full-fledged style as A. most people won't bother themselves to follow it and B. if it looks hard most people won't bother to write documentation at all.

True, but here we are only talking about m_pd.h at the moment. It wouldn't be an ongoing undertaking (new functions are added very rarely), but rather a large one-time effort. Internal documentation would also be great, but there I would already be happy about regular code comments :-)

I think every function in m_pd.h should at least have \brief. We might also use \param and \return unless the arguments or return values are self-explanatory.

We could actually have more detailled documentation and usage examples in a seperate document and then in m_pd.h add links to the relevant sections. Maybe there is even a way to link to sections in the "Externals How-To" with Doxygen? This would be ideal because then we wouldn't have to maintain two seperate documents.

[umlaeute]

to start the schism early: i very much prefer @brief over \brief (i like LaTeX, but not in my code) 🤦

[Lucarda]

Maybe there is even a way to link to sections in the "Externals How-To" with Doxygen?

Shouldn't be hard with CI or "webhooks" into the #35 repo.

some auto CI or webhooks like:

git clone pd;
run doxygen to build on output-folder "foo"
clone #35
copy "foo" to #35/static/foo
run hugo for #35

The site is up including the doxygen part.

[danomatika]

to start the schism early: i very much brefer @brief over \brief (i like LaTeX, but not in my code) 🤦

Ugg no. ;) As I've suggested, I'd prefer a minimal of either.