> 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 > >
