Thanks for this Walter. It's good to see the developer docs get some love too.
In my defense, I will write full javadocs documentation for Pirk's APIs (i.e. public and protected types/methods), but tend to write comments for private and package level access types/methods that are designed to be read alongside the code (i.e. /* ... rather than /** ...). I admit that is a style/pragmatic approach, so no objection that you are tackling the fuller documentation across the board. Coming late to the code review... when writing the javadoc, we should complete the tags text, so rather than simply writing "@throws PIRException" with no explanation, those lines should go on to explain why the exception may be thrown. Regards, Tim On 06/08/16 01:05, wraydulany wrote: > GitHub user wraydulany opened a pull request: > > https://github.com/apache/incubator-pirk/pull/48 > > [Pirk 38]: Update Javadocs for Schema Loaders > > > > You can merge this pull request into a Git repository by running: > > $ git pull https://github.com/wraydulany/incubator-pirk PIRK-38 > > Alternatively you can review and apply these changes as the patch at: > > https://github.com/apache/incubator-pirk/pull/48.patch > > To close this pull request, make a commit to your master/trunk branch > with (at least) the following in the commit message: > > This closes #48 > > ---- > commit 6f214b768acb314df7785eedbea5f2f8342906d3 > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-01T11:15:03Z > > Updated javadocs and some other comments for user and developer > > commit 7491376dd5e161b20fa6221c9ac06c7dd3575f74 > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-01T15:35:37Z > > Minor changes to words, remove errantly added import. > > commit f5870b9cb3124733096dcb82d9911eb54de38639 > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-01T15:38:53Z > > Minor changes to words, eliminate unnecessary complexity in link name > > commit 956ae54332f6d1ecf2523ebbe977f7ac683386a2 > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-01T15:45:41Z > > Yet more minor but useful changes to words > > commit 37406b08197e5937f917fe1ee866e5d0ee7ddb51 > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-02T13:54:29Z > > Documenting that element names are case sensitive > > commit c6f6549a00fb30aa6fc435a220aa1c2a739a4f8b > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-04T13:31:01Z > > Now updating comments for QuerySchemeLoader > > commit 23568fc1688792b87d4379d3bedfc1cdaf44d371 > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-04T13:32:52Z > > Merge remote-tracking branch 'upstream/master' into PIRK-38 > > commit 3726f36de429e32cb2372546b9b2712a5aacd3a9 > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-04T15:05:36Z > > A few more comment updates for the DataSchemaLoader > > commit dcaf4210dfa5ecce5aab6307126b56b5b07bba3d > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-04T19:54:22Z > > Turn all the pre-function comments to javadocs; fix a tag. > > commit c46ed6042d29510e1e653e5996b9ab2bcf2bce7c > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-04T22:36:51Z > > QuerySchemaLoader: Turn all the pre-function comments to javadocs; fix a > tag. > > commit 08e58c758ae579170239e826fcaa83250718e4c7 > Author: Walter Ray-Dulany <[email protected]> > Date: 2016-08-04T22:39:42Z > > I wish that I could reference members and methods in a javadoc link; > alas, no. > > ---- > > > --- > If your project is set up for it, you can reply to this email and have your > reply appear on GitHub as well. If your project does not have this feature > enabled and wishes so, or if the feature is enabled but not working, please > contact infrastructure at [email protected] or file a JIRA ticket > with INFRA. > --- >
