"Documentation by paper"

[Richard Kenner]

    > How could I possibly write documentation on code that I need
    > documentation to understand?  Any documentation I could write would
    > be totally useless!

    why do you say that?  I think it's generally not that hard to
    approach unfamiliar code and add documentation when I figure out
    what it's doing.

Yes, you can often add missing comments in the body of a function, but the
really important comments, as Robert says, are *why* things are done the
way they are done and what it *intended* to be done.  All you're ever
going to be able to figure out is what *is* being done no matter how
long you look at the code.


    /* Write a function, `added_clobbers_hard_reg_p' this is given an insn_code
       number that needs clobbers and returns 1 if they include a clobber of a
       hard reg and 0 if they just clobber SCRATCH.  */

    I don't have much idea what that comment means, mostly because the
    function name 'added_clobbers_hard_reg_p' doesn't make sense to me.  I
    don't know what the 'added' refers to.

Ooops.  Typo: "this is given" should be "that is given".

    that was also a change you made.  so, starting from the assumption
    that you're not an idiot, I can work on reconstructing your logic,
    which involves looking at insn_invalid_p's callers, digging into
    mailing list discussions, asking you, etc.  after doing all that, I
    could submit patches that summarize what I find, so other people don't
    have to go through the same investigative process.  but all that's too
    much work right now.  I have other things I need to do.  maybe later.

Yes, but note that all of that is about *one* comment on *one* function.
The major issue here isn't the comments on individual comments, but
missing multiple paragraphs that explain an overview of how things
are supposed to work.