mesos-reviews mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Adam B" <a...@mesosphere.io>
Subject Re: Review Request 35961: Include protobuf classes in generated Javadoc.
Date Sat, 27 Jun 2015 18:59:57 GMT

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


Thanks for doing this Connor! Just a couple of questions about javadoc parsing of html (I'm
no expert, just googled a few things).
Do we need to do a pass over our protos now to convert any `//` or `/*` block comments to
`/**` comments? Worth a follow-up JIRA/patch? Most of mesos.proto looks fine, except TrafficControlStatistics
and ResourceStatistics. And I'm not sure how public these need to be, but messages.proto is
all `//` style, or completely missing comments.


src/java/generated/org/apache/mesos/MesosNativeLibrary.java.in (lines 27 - 36)
<https://reviews.apache.org/r/35961/#comment142283>

    Did you verify that the curly-braces are properly handled here? I read on http://stackoverflow.com/a/13512524/4056606
that the `{@code` tag will interpret the first closing brace as its own ending brace. In fact,
@code may only be necessary for wrapping Generic `<something>` declarations. You could
additionally/instead use the old-style `<code>` tag to print everything in code-font.
I would hope this would be easier, but parsing code within docs within code must be difficult.
Don't even try to put `/*` block comments inside your code example, or the compiler will get
confused too.



src/java/mesos.pom.in (line 134)
<https://reviews.apache.org/r/35961/#comment142284>

    Is `${project.basedir}/generated` any better/different than `@abs_top_builddir@/src/java/generated`



src/java/src/org/apache/mesos/MesosExecutorDriver.java (line 31)
<https://reviews.apache.org/r/35961/#comment142282>

    Oracle docs (and wikipedia) claim that javadoc only uses the opening <p> tag, without
the closing </p> tag. Did you find that this rendered incorrectly?


- Adam B


On June 26, 2015, 6:18 p.m., Connor Doyle wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/35961/
> -----------------------------------------------------------
> 
> (Updated June 26, 2015, 6:18 p.m.)
> 
> 
> Review request for mesos, Adam B and Ben Whitehead.
> 
> 
> Bugs: MESOS-1552
>     https://issues.apache.org/jira/browse/MESOS-1552
> 
> 
> Repository: mesos-incubating
> 
> 
> Description
> -------
> 
> Updates the Java POM to include the generated Java protobuf classes.
> 
> 
> Diffs
> -----
> 
>   src/java/generated/org/apache/mesos/MesosNativeLibrary.java.in c54d903 
>   src/java/mesos.pom.in 138da55 
>   src/java/src/org/apache/mesos/MesosExecutorDriver.java 1b5ed60 
> 
> Diff: https://reviews.apache.org/r/35961/diff/
> 
> 
> Testing
> -------
> 
> - configure
> - make
> - Manual verification of generated Javadoc HTML
> 
> 
> Thanks,
> 
> Connor Doyle
> 
>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message