doc design decisions in code??

[Colin Froggatt]

Hi Guy's, I've jsut completed the code and the javadoc but I came across this line in the spec <p>

Design decisions should be clearly but briefly described in your comments.

Now, does this mean in the design doc or in the actual code comments (javadoc)? Any opinions and advice greatfully accepted.

[Adam Roberts]

More in the design.txt than anything.
Javadoc simply tells what each method does, although placing mention of notable design decisions in the javadoc certainly doesnt hurt anything.