You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@drill.apache.org by Daniel Barclay <db...@maprtech.com> on 2015/01/09 19:51:51 UTC
Re: Review Request 29278: Drill-1904 package level docs
-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/29278/#review67478
-----------------------------------------------------------
I think a next step for the package-level documentation is to put the packages into
Javadoc groups to organize and order the package listing on the Javadoc overview page.
(See http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#group and
http://maven.apache.org/plugins/maven-javadoc-plugin/examples/group-configuration.html .)
The packages for Drill's "published" APIs should probably be in the first group or
groups, to make it easy for us to see how they and their documentation is shaping up.
(The "published" APIs are the logically public (not just Java-public) APIs intended for
developer end users (developers developing against Drill, not developing Drill itself),
e.g., the Java Drill client API (DrillClient, UserClient, etc.), the Drill JDBC API, the
storage plugin provider API, and presumably the Drill server invocation API (Drillbit,
DrillConfig, etc.)
Since the end-user documentation probably should include a separately generated Javadoc
bundle that includes only the published interfaces (since developer end users won't care
about internal interface, and for more visibility of the code and the results of the
Javadoc comments we're starting to add, at least for now this developer bundle should
be generated with "-private".)
The next groups should probably be for major subcomponents, probably in bottom-up order,
except that generated classes should probably be last (to keep them out of the away) (if
we don't suppress them).
Editorial wording fixes:
- "Execution time exceptions." -> "Execution-time exceptions."
- "Java-based client for ..." -> "Java client API for ..." (since it's not a whole client, but the Java library for a client program to use for "...").
- "Drill execution engine, includes: ..." -> "Drill execution engine, including: ..." OR "Drill execution engine; includes: ..."
- "Logical (execution engine independent) element definitions." -> "Logical (execution-engine-independent) element definitions."
- "Connected graph representation " -> "Connected-graph representation"
- "Runtime code generation, compilation and bytecode manipulation utilities." -> "Runtime code-generation, compilation and bytecode-manipulation utilities."
- 'A single node 'cluster coordinator' used when running Drill locally.' -> 'A single-node "cluster coordinator" used when running Drill locally.' (Or "A single-node cluster coordinator used when running Drill locally.")
- "Interface for drill's interaction ..." -> "Interface for Drill's interaction ..."
- (The first-line package descriptions are nicely consistent (all noun phrases).)
- "Sub package: data - logical operators This package includes":
- "Sub package" -> "Subpackage"
- "operators This" -> "operators. This"
- "data - logical operators" -> "data: logical operators"
- "data" -> {@link org.apache.drill.common.logical.data}
- "a JDBC driver is available as well, see ..." -> "a JDBC driver is available as well; see ..." ->
- (nice linking to org.apache.drill.jdbc)
- "for generating type specific java code" -> "for generating type-specific Java code"
- "prompt runtime code generation for the expressions needed to for the operator to process" -> "prompt runtime code generation for the expressions is needed for the operator to process" ?
- "to re-compile and JIT optimize the" -> probably "to re-compile and JIT-optimize the"
- "stitching together runtime generated code with" -> "stitching together runtime-generated code with"
- "for small data only objects" -> "for small data-only objects"
- "defining user facing APIs" -> "defining user-facing APIs"
- "Interface for drill's interaction" -> "Interface for Drill's interaction"
- "... support 'spilling to disk'. These ...": Switch to double quotes (American English standard).
- "limits of a single machines memory" -> "limits of a single machine's memory"
- "other cluster persistent state" -> maybe "other cluster-persistent state" or "other cluster-wide persistent state" or maybe "other persistent cluster state"
Daniel
- Daniel Barclay
On Dec. 19, 2014, 11:40 p.m., Jason Altekruse wrote:
>
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/29278/
> -----------------------------------------------------------
>
> (Updated Dec. 19, 2014, 11:40 p.m.)
>
>
> Review request for drill, Daniel Barclay and Jacques Nadeau.
>
>
> Bugs: Drill-1904
> https://issues.apache.org/jira/browse/Drill-1904
>
>
> Repository: drill-git
>
>
> Description
> -------
>
> Add package level documentation to the sources of Drill
>
>
> Diffs
> -----
>
> common/src/main/java/org/apache/drill/common/config/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/exceptions/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/expression/aggregate/BasicAggregates.java 5f18aaf
> common/src/main/java/org/apache/drill/common/expression/fn/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/expression/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/expression/types/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/expression/visitors/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/graph/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/logical/FormatPluginConfig.java 936e4f2
> common/src/main/java/org/apache/drill/common/logical/FormatPluginConfigBase.java 0704085
> common/src/main/java/org/apache/drill/common/logical/data/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/logical/data/visitors/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/logical/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/types/package-info.java PRE-CREATION
> common/src/main/java/org/apache/drill/common/util/package-info.java PRE-CREATION
> contrib/storage-mongo/src/main/java/org/apache/drill/exec/store/mongo/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/cache/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/client/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/compile/bytecode/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/compile/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/compile/sig/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/coord/local/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/coord/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/coord/zk/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/disk/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/dotdrill/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/exception/package-info.java PRE-CREATION
> exec/java-exec/src/main/java/org/apache/drill/exec/package-info.java PRE-CREATION
>
> Diff: https://reviews.apache.org/r/29278/diff/
>
>
> Testing
> -------
>
> Just comments, no code changes
>
>
> Thanks,
>
> Jason Altekruse
>
>