I don't have enough experience on the Java/Javadoc side to make a specific suggestion, but with other languages I've used Sphinx and Doxygen with great results.
Jon On Tue, Dec 20, 2016 at 11:29 AM Michael Miklavcic < [email protected]> wrote: > Were you thinking javadoc or something more? I wouldn't mind seeing us > produce a javadoc site, if we aren't already doing so. > > On Dec 20, 2016 9:25 AM, "[email protected]" <[email protected]> wrote: > > > Regarding documentation - while I'm not a huge fan of that approach (I > > would prefer to see documentation generated from the code), I think it > > could work in the short term. Having that outlined both in the coding > > guidelines and on the wiki would be important. > > > > I agree with the comments about author != committer, and 100% code > > coverage. > > > > Jon > > > > On Tue, Dec 20, 2016 at 11:10 AM James Sirota <[email protected]> > wrote: > > > > > In my view the lower-level documentation that should be source > controlled > > > with the code belongs on github and then use case documentation and > > > top-level architecture diagrams belong on the wiki. What do you think? > > > > > > I think if the author is not a committer and can't merge then the > > reviewer > > > should probably merge or the PR originator should ping the dev board to > > get > > > someone to merge the PR in. Does that seem reasonable to everyone? > > > > > > 18.12.2016, 13:10, "Kyle Richardson" <[email protected]>: > > > > Couple of questions/comments: > > > > > > > > In 2.4, we talk about Javadoc and code comments but not too much > about > > > the > > > > user documentation. Should we, possibly in a section 4, give some > > > > recommendations on what should go into the README files versus on the > > > wiki? > > > > This could also help the reviewer know if the change is documented > > > > sufficiently. > > > > > > > > In 2.6, we say that 1 qualified reviewer (Apache committer or PPMC > > > member) > > > > other than the author of the PR must have given it a +1. In the case > > > where > > > > the author is not a committer (who could merge their own PR), should > we > > > > state that the reviewer will be responsible for the merge? > > > > > > > > -Kyle > > > > > > > > On Fri, Dec 16, 2016 at 6:39 PM, James Sirota <[email protected]> > > > wrote: > > > > > > > >> Lets move this back to the discuss thread since it's still > generating > > > that > > > >> many comments. Please post all your feedback and I will incorporate > > it > > > and > > > >> put it back to a vote. > > > >> > > > >> Thanks, > > > >> James > > > >> > > > >> 16.12.2016, 16:12, "Matt Foley" <[email protected]>: > > > >> > +1 > > > >> > > > > >> > In 2.2 (follow Sun guidelines), do you want to add the notation > > > “except > > > >> that indents are 2 spaces instead of 4”, as Hadoop does? Or does > the > > > Metron > > > >> community like 4-space indents? I see both in the Metron code. > > > >> > > > > >> > My +1 holds in either case. > > > >> > --Matt > > > >> > > > > >> > On 12/16/16, 9:34 AM, "James Sirota" <[email protected]> wrote: > > > >> > > > > >> > I incorporated the changes to the coding guidelines from our > > discuss > > > >> thread. I'd like to get them voted on to make them official. > > > >> > > > > >> > https://cwiki.apache.org/confluence/pages/viewpage. > > > >> action?pageId=61332235 > > > >> > > > > >> > Please vote +1, -1, 0 > > > >> > > > > >> > The vote will be open for 72 hours. > > > >> > > > > >> > ------------------- > > > >> > Thank you, > > > >> > > > > >> > James Sirota > > > >> > PPMC- Apache Metron (Incubating) > > > >> > jsirota AT apache DOT org > > > >> > > > >> ------------------- > > > >> Thank you, > > > >> > > > >> James Sirota > > > >> PPMC- Apache Metron (Incubating) > > > >> jsirota AT apache DOT org > > > > > > ------------------- > > > Thank you, > > > > > > James Sirota > > > PPMC- Apache Metron (Incubating) > > > jsirota AT apache DOT org > > > > > -- > > > > Jon > > > > Sent from my mobile device > > > -- Jon Sent from my mobile device
