Mandatory Method Documentation

Question

In my previous work, providing all methods using javadoc was mandatory, which led to the following things:

/**
 * Sets the Frobber.
 *
 * @param frobber The frobber
 */
public setFrobber(Frobber frobber) { ... }

As you can see, the documentation takes up space and works, but adds little code.

Should all methods be documented as required or optional? Is there a rule for which methods to document? What are the pros and cons of documenting each method?

Answer 1

"providing all methods with javadoc was mandatory"

, , javadoc , , , , .

, javadoc, javadoc - , HTML, , ..

, , , . - XML - . , // Sets this object to use the specified frobber for all future frobbing, javadoc .

, , this , set() frobber, while(!frobber.isset()) { refrigerator.add(frobber); sleep(3600); refrigerator.remove(frobber); } , " frobber". , - , "set" - OED. , , , - , , , , . , " frobber" "frobber" IDE javadoc-. , frobbing (, ), , .

- , . Java interface s, "" - , . , , . , - , , .

, IMO . , cone of shame , - , .

, , , , . , , , , . , " javadoc ", , , , .

Answer 2

/ , , . . , , , , , , . .

Answer 3

. - . , , .

, , . , -, , , , . , , , .

:

, , , , .

:)

Answer 4

"" . , (, < 10 ), . - , , - !

InfoQ.

Answer 5

. Javadoc ( ) - . , Javadoc . , , , .

, , . , , , . , 0 1. .

- . Frobber, setFrobber . Javadoc, , . frobIt , 3 . .

​​ Javadocs ither, . , .

Answer 6

: ?

A: .

Q: , ?

A: .

: ?

A: : , , . . . : Whining. .

• , .

• get set . . , . , , .

: . , eh?