A standard and testing infrastructure for function-level documentation of Kaleidoscope

[jesse]

@merlin

All of my experience indicates to me that documenting code as it’s being written, rather than waiting until it’s stable, does not result in taking longer to get it stable, and leads to better quality at all points in time. Especially on open-source projects, where neglecting documentation leads to a situation where many people are effectively prevented from contributing, and others try despite a lack of understanding, and almost inevitably introduce bugs that could have been avoided.

You’re not wrong. It’s something we need to get better at.

I’d love to talk about concrete steps to improve the situation. One of those steps is figuring out a clean, simple, standard way to write function-level documentation and automated tests for it. I know what the right answers are for Perl, Ruby and Java. In general, I’ve not seen good examples in Arduino-land and I don’t know the C++ world well enough.

Do you have recommendations? Does anyone else have recommendations?

Though we’re spinning out on a tangent from the original topic here. I’m going to reparent these posts to a new topic.