Is it just me? Or does writing doxygen style comments… just feel unnatural?
Current Doxygen Example
Take for instance below with lots of usage of special ‘tags’. Especially with repeated \param and the smattering of keywords. below example from here
/// Copy a string.
/**
The strcpy function copies \a strSource, including
the terminating null character, to the location
specified by \a strDestination. No overflow checking
is performed when strings are copied or appended.
The behaviour of \a strcpy is undefined if the source
and destination strings overlap.
\param strSource pointer to source null terminated string
\param strDestination pointer to destination memory
\return \a strcpy returns the destination string.
No return value is reserved to indicate an error.
\sa wcscpy(), _mbscpy(), strncpy()
*/
char* strcpy(char* strDestination, const char* strSource);
Proposal for an “Application Note” to cover this topic?
Is there a way that commonmark can inform how code documentation generation should be done? Perhaps as a “application note” section within the commonmark community (Not part of the core standard, but as best practices).
What it seems is that the issue with doxygen comments is that there is a need for transparent section that are tagged keyword sections.
What if above doxygen example was rewritten only for humans to read?
The above if written purely for humans only may look like below. You can see a clear difference in readability.
/// Copy a string.
/**
The strcpy function copies [[strSource]], including
the terminating null character, to the location
specified by [[strDestination]]. No overflow checking
is performed when strings are copied or appended.
The behaviour of [[strcpy]] is undefined if the source
and destination strings overlap.
# Parameters:
* strSource : pointer to source null terminated string
* strDestination : pointer to destination memory
# Return:
[[strcpy]] returns the destination string.
No return value is reserved to indicate an error.
See Also: wcscpy(), _mbscpy(), strncpy()
*/
char* strcpy(char* strDestination, const char* strSource);
A more realistic/practical take of a commonmark based code annotation
However while I like the above best. It may be hard to distinguish between “human sections” and “human/machine” sections. So perhaps <keyword>:: <content> (or # <keyword>::<content>) would be a good way to transparently note these special sections.
/// Copy a string.
/**
The strcpy function copies [[strSource]], including...
# normal section
normal documention notes and explanations... etc...
Parameters::
- strSource : pointer to source null terminated string
- strDestination : pointer to destination memory
Return::
[[strcpy]] returns the destination string.
See Also:: wcscpy(), _mbscpy(), strncpy()
*/
char* strcpy(char* strDestination, const char* strSource);
Other interesting thoughts
- Perhaps instead of saying
The strcpy functionor[[strcpy]]in the same function description. Maybe the generator is smart enough to interpretThis functionorThe functionin the first sentence as referring to the current function.