search

jamoma / jamoma2

A header-only C++ library for building dynamic and reflexive systems with an emphasis on audio and media.
MIT License
30 stars 6 forks source link

Discuss length of class desciptions for Doxygen comments #52

Open nwolek opened 8 years ago

nwolek commented 8 years ago

@tap added several comments back into the LowpassFourPole file here: https://github.com/jamoma/jamoma2/commit/2366d060d6992a6881e9eb3a4facfde8468ebc5e

My initial goal was to provide "just enough" useful information for that side panel in Xcode. The comments in a few places are now so long that they require quite a bit of scrolling and I find the information to be too much. I don't dispute that more information is good to document, but I don't think these class descriptions are the right place for it.

How long do we want these class descriptions to be? If we make them shorter, where should the additional information go?

tap commented 8 years ago

It might be useful to see how this is handled in other software codebases. Or it might not be useful.

One aspect of the header-only approach we are using that I find very compelling is that we have a single authoritative place for all knowledge about a specific implementation. It's like being DRY but at more of a "meta" level.

To that end, I feel that it is very desirable to have this type of information in this file -- keeping the documentation local to the implementation. Perhaps there are ways within that could ease the burden of information overload. I'm not sure if/how Xcode handles Doxygen "discussion" tags (or whatever they're called). Etc.