Documenting Source Code

[Mysore S Dattatreya <datta -at- WIPINFO -dot- SOFT -dot- NET>]

Dear Techwhirlers,

I have an interesting question up my sleeve.  Recently, I have been
given the responsibility of documenting source code written in C.  The document should
describe entity relationships and many more associated with source codes.
Can anyone point me to a ready reckoner that describes "do's and don'ts"
on creating such documentation.  I have downloaded Prof. John Renish's
book list but it does not seem to have any.  The list is huge and probabilities
are that I cannot identify one, even if it were listed.  I have seen "Code Complete"
by Steve McConnel but it does not seem to meet my requirements.  I have also
seen the Microsoft Manual of Style but the information is very sketchy.

I have yet another question on documenting for hardware projects.  These projects
involve documenting codes written in Verilog and other high level languages specific
to ASICs.  My question is pertaining to an example which I shall quote:

This is the description of a signal and it is as below:

"The PERR# pin is sustained tri-state and is driven active by the agent receiving
data two clocks following the data when a data parity error is detected."

Is there any way that this can be made readable and simpler?  Are there any style
guides avaiable whilst documenting such information?  There are many such instances
and surprisingly these are part of the IEEE specifications.  I am not aware if this is
the method followed while documenting signal descriptions.  Correct me if I am wrong.
I am badly in need of some direction.  Can someone help me out?

Thanks for the help and expecting tonnes of information, suggestions and advice
on this score.

Best regards to every body out there.

Dattatreya M S
Senior Technical Writer
Wipro Technology Solutions
Bangalore, India.