> On July 9, 2015, 10:24 p.m., Marco Massenzio wrote:
> > src/master/http.cpp, line 307
> > <https://reviews.apache.org/r/36318/diff/2/?file=1003768#file1003768line307>
> >
> >     while you are at it, do you mind adding javadoc doxy documentation to 
> > this method?
> >     what it does, what the @param's are, what does it return; maybe a link 
> > to the design doc...
> >     
> >     as much as you feel like, really: like money and beauty, there's no too 
> > much documentation :)
> 
> Anand Mazumdar wrote:
>     There is already a TODO on the CALL_HELP variable for documenting this 
> better. This can easily be pursued as part of that. Do you still want me to 
> pursue this as part of this review ?
> 
> Marco Massenzio wrote:
>     Yes, please - the more documentation we add, the less we avoid repeating 
> the effort (that you must have just done) of reverse-engineering the code and 
> understanding what it does.
>     
>     Like money and beauty, there is no such thing as too much documentation :)
> 
> Anand Mazumdar wrote:
>     Same as above, not an public API method.

> Like money and beauty, there is no such thing as too much documentation :)

We strive to write code that is clear without needing lots of documenation!

Please be thoughtful about documentation, documentation is prone to rot and 
excessive documentation poses a higher maintenance burden. Ultimately, the code 
is always the source of truth. That being said, I do agree that we should 
document our libraries and anything that is not intuitive!

While I agree with the intent.. I find this kinds of broad generalization 
counter-productive to what we're trying to accomplish, clearly if we had 10x 
the amount of documentation as we have code, we will be crushed under the 
maintenance burden / verbosity, no?


- Ben


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/36318/#review91213
-----------------------------------------------------------


On July 15, 2015, 4:56 a.m., Anand Mazumdar wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/36318/
> -----------------------------------------------------------
> 
> (Updated July 15, 2015, 4:56 a.m.)
> 
> 
> Review request for mesos, Benjamin Hindman, Ben Mahler, Isabel Jimenez, Marco 
> Massenzio, and Vinod Kone.
> 
> 
> Bugs: MESOS-2294
>     https://issues.apache.org/jira/browse/MESOS-2294
> 
> 
> Repository: mesos
> 
> 
> Description
> -------
> 
> This change lays the ground-work for the master's ability to stream events 
> back to the client. This review turned out a bit too large for my own liking 
> but in a nutshell, it just takes a subscribe request and puts a subscribed 
> event back on the stream.
> 
> Explanation of changes:
> - Made a generic FrameworkDriver interface that the master now uses to 
> communicate with the frameworks instead of just invoking 
> send(framework->pid,...)
> - FrameworkDriver can be of 2 types http, libprocess. An Optional member 
> variable is used to distinguiush between them.
> - This still uses hard-coded http related constants. They can go away when 
> Isabel submits her validation change (36217)
> - This change prefers use of using trailing under-scores as member variables 
> from the style guide.
> 
> 
> Diffs
> -----
> 
>   src/common/protobuf_utils.hpp afe5a85d3f58eaabb16807253c5fcc07cabcf8e8 
>   src/common/protobuf_utils.cpp 9ac81c38efd70f92c64a5865fa79fe516e84dd92 
>   src/master/http.cpp 23a6d4bd2f60cb4a4ad463aea7cc032941578bdc 
>   src/master/master.hpp 2343a684402972a8c336c0dcdde0bfaffabe7cec 
>   src/master/master.cpp b877676afa6f3833eb7d2fb06beeaa288bd8bd5d 
>   src/tests/http_api_tests.cpp 64bbeb6699171e85a5be293919ad9f32ded0ebac 
> 
> Diff: https://reviews.apache.org/r/36318/diff/
> 
> 
> Testing
> -------
> 
> make check + a simple test for subscribe call received a subscribed event 
> back on the stream.
> 
> 
> Thanks,
> 
> Anand Mazumdar
> 
>

Reply via email to