[
https://issues.apache.org/jira/browse/DRILL-3496?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14652490#comment-14652490
]
Jason Altekruse commented on DRILL-3496:
----------------------------------------
In /java/org/apache/drill/common/config/DrillConfig.java line 166"
- private static DrillConfig create(String overrideFileName, Properties
overriderProps, boolean enableServerConfigs) {
- overrideFileName = overrideFileName == null ?
CommonConstants.CONFIG_OVERRIDE : overrideFileName;
-
- // first we load defaults.
+ /**
+ * ...
[~jaltekruse] - I haven't seen this convention before, but I assume this means
that the docs for similar methods suffice and don't need to be repeated here. I
would possibly recommend moving the longer comment above to here, in which case
I think it would be possible to just put "..." above all of the alternative
implementations of this method. I think it makes the most sense to put the
comment describing the general idea of the functions purpose above the version
that also describes what all of parameters can do.
[~dsbos] - [Reply via e-mail because I don't currently see this comment of
yours on the pull-request page.]
> + /**
> + * ...xx
I haven't seen this convention before, but I assume this means that the docs
for similar methods suffice and don't need to be repeated here.
No, actually it was an attempt to indicate that I hadn't addressed the method
description (the part before the parameters), and not intended to mean
"otherwise same as above".
I was trying to quickly at least document the parameter (add the reference to
the other existing text) without taking time to fill in the whole documentation
comment.
Would simply leaving the method description part blank be better than using
"..."?
[~jaltekruse] - I think if you should just put in explicit todo. However I'm
not even sure that it makes sense to document these methods individually. There
is a comment that is very descriptive about what all of these do, it's just
above the wrong version of the method. If you move it above the one that takes
all of the parameters, I think it would be fine to even leave out the parameter
descriptions on the other versions and have a common message directing people
to the one descriptive comment (which also describes all possible parameters).
No need for a todo, not a bunch of work up front.
[~dsbos] -
>> I'm not even sure that it makes sense to document these methods individually.
If a method is not documented individually, then viewing that method's
documentation isn't going to yield much information--remember that people don't
see comments just in the context of the surrounding source code, but also in
IDEs (e.g., showing one method's documentation at a time) and in generated
Javadoc pages.
> Augment logging in DrillConfig and classpath scanning.
> ------------------------------------------------------
>
> Key: DRILL-3496
> URL: https://issues.apache.org/jira/browse/DRILL-3496
> Project: Apache Drill
> Issue Type: Bug
> Reporter: Daniel Barclay (Drill)
> Assignee: Jason Altekruse
>
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
