We're only using non-javadoc comments for APIs, which are mostly in headers. We're still using // based C++ comments in implementations and places we don't want to be picked up via doxygen.
On Thu, Jul 9, 2015 at 5:23 PM Benjamin Mahler <[email protected]> wrote: > 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 >
