A couple of thoughts:
(1) When introducing javadoc comments, can we please keep comment style
consistent within files and APIs? For the most part, it seems folks are
introducing javadoc in consistent sweeps, which is great. However, it looks
also like there are reviews and commits where we are introducing javadoc +
non-javadoc within a file / api, would love to avoid the inconsistency. :(
(2) Where are we planning to introduce javadoc comments? APIs only? All
headers? Would love to see some communication around how we'd like folks to
be proceeding. Maybe I missed it, but can't seem to find an email with this.
(3) I ask because there is a tradeoff: we make the code more verbose to
navigate visually. Also, sometimes we document things unnecessarily:
/**
* Sends a message with data without a return address.
*
* @param to Receiver of the message.
* @param name Name of the message.
* @param data Data to send (gets copied).
* @param length Length of data.
*/
void post(const UPID& to,
const std::string& name,
const char* data = NULL,
size_t length = 0);
Here, having a 'to' or 'receiver' as a variable name is pretty
self-evident, ditto for 'messageName', 'data', 'length'. Are we ok with
omitting these kinds of comments? It seems like we have to be asking
ourselves when this provides value. Thoughts?
Ben
