s/non-/
> On Jul 10, 2015, at 2:27 AM, Benjamin Hindman <[email protected]> wrote:
>
> 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
>>
