Commonmark usage in code documentation? (E.g. like doxygen)


#1

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 function or [[strcpy]] in the same function description. Maybe the generator is smart enough to interpret This function or The function in the first sentence as referring to the current function.

#2

have you seen https://recommonmark.readthedocs.io ?


#3

seems that docutls and recommonmark is about standalone documentations.

does it parse and analyse sourcecode like doxygen?