This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: "Documentation by paper"


    And totally useless unless one goes into the source code to read it.

I think you're making that statement irrespective of the formatting of
the comments and I agree.

    IMHO that's actually a huge long term liability as it actually
    discourages writing good API interfaces and documenting them, while at
    the same time encourages developers to actually look at the
    implementation to determine if the code in question actually does what
    they want.

I'm not sure what "that" means in your first line above.

The problem I have with automatic documentation systems is that they
encourage a "fill in the checklist" mentality to documentation.  In other
words, programmers tend to feel that since they've filled in all the blanks,
they've written good documentation. Lots of industrial code looks that way.

But actually the quality of documention can't be measure by any metric.  The
ideal documentation is what's needed to explain the code. Less than that
isn't sufficient, but more than that adds clutter.  No mechanical system can
create that quality of work.  There are 500-line functions that are totally
clear without any comments and where adding comments is clutter and there are
10-line functions that need a few paragraphs of comments.

Writing quality documentation is an art, much like writing good code.
Mechanizing things doesn't help.  It's far easier to do a good job
documenting a function if you're writing a paragraph consisting of English
sentences than filling in the blanks.

For example, if I have a function with four parameter named FIRST1, LAST1,
FIRST2, and LAST2, simply saying "The four parameters are the ranges of two
insn chains that we are comparing" is completely fine to document what the
parameters to.  Writing:

	* @param first1 RTL pointer to head of insn chain 1
	* @param last1  RTL pointer to tail of insn chain 1
	* @param first2 RTL pointer to head of insn chain 2
	* @param last2  RTL pointer to tail of insn chain 2

actually says *less* than the above sentence and is a *huge* amount of
totally unnecessary clutter.

    Now having said that, I've never liked reading doxygen annotated
    comments; I find the annotations make the comments harder to read.
    Unfortunately, I don't have a better solution.

To what problem?


Also, can I take this discussion of annotations to mean that everybody agrees
with my original message about using papers and textbooks as substitutes to
documentation?


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]