On Fri, 23 May 2008 14:32:13 +0900, Emmanuel Lecharny
<[EMAIL PROTECTED]> wrote:
이희승 (Trustin Lee) wrote:
On Fri, 23 May 2008 12:44:00 +0900, Emmanuel Lecharny
<[EMAIL PROTECTED]> wrote:
이희승 (Trustin Lee) wrote:
On Fri, 23 May 2008 12:21:43 +0900, Emmanuel Lecharny
<[EMAIL PROTECTED]> wrote:
이희승 (Trustin Lee) wrote:
On Fri, 23 May 2008 12:02:45 +0900, Emmanuel Lecharny
<[EMAIL PROTECTED]> wrote:
이희승 (Trustin Lee) wrote:
Every public methods except for the constructors are overridden
from its supertypes and interfaces. They all got proper JavaDoc
comments. Let me know if I am missing something.
Adding a @see Class#method() in the implementation then should
help. When you look at a method javadoc it's better to know where
too look at : the intheritance scheme can be feilry complex, and
it can be a burden to retreive the associated Javadoc.
Something like :
/**
* @see javax.naming.Context#close()
*/
public void close() throws NamingException
...
I'd just move the cursor on the method? That shows pretty nicely
rendered JavaDoc in modern IDEs.
Sometime, you just have to use vi or emacs. Make it simple for users
: add a @see tag. Cost almost nothing, and it helps.
I wouldn't bother with vi or emacs. They pay for what they use.
Moreover, it's not 'almost nothing'.
-1.
Please revert the commit.
-1. I have a valid point not to add those @see tags.
If you really want to see them added, add them by yourself. I disagree
with what you suggest anyway.
Now you are behaving like a manager, who is a bladder but does no
actual action.
Trustin, I'm on the project *management* committee.
I know. Why would I say that then?
I would like to see the code you commit adheres to some standard.
Until this is resolved my right to veto holds so please revert your
commit until we figure out the best choice for Javadoc. If you won't
revert it, I can do it for you.
What's apparent is that:
* @see is not appropriate for this case.
* Duplication is bad and it costs a lot of maintenance burden for us.
for GOOD reason.
Regardless of which we choose something is required to help those using
IDE's besides Eclipse. There is no reason why Vi or Emacs users should
according to your words, 'pay for what they use'.
You should say IDEs besides Eclipse, NetBeans and IntelliJ. Then...
what's left? Vi and Emacs? They just chose the wrong tool to navigate
Java source code.
I also have to mention that I don't like to go that far. I have to just
in order to get this project on rails. You have to understand that you
can't break all the rules simply because you think that the rules are
bad.
I didn't made the rules, and I consider that good practices are also
rules we have to follow. If all the implemented classes in the core JVM
(ArrayList and List, etc) duplicate the Javadoc, it's for a pretty good
reason.
You can disagree, but that won't make those good reasons disappear.
They didn't duplicate JavaDoc but rewrote or amended the original JavaDoc
to clarify the implementation detail or performance characterstics. If
you look into more classes more in detail, you will even see empty JavaDoc
blocks.
Your good reason is not always others' good reason. You already saw
disagreement in using @see tags and duplicating JavaDoc.
It simply doesn't make a sense to revert back a chunk of working
implementation because of subtle documentation issue (I am even suspicious
that it's really an issue).
PS : for the record, here is the veto definition
(http://www.apache.org/foundation/glossary.html) :
*Veto*
According to the Apache methodology, a change which has been made or
proposed may be made moot through the exercise of a veto by a
committer to the codebase
<http://www.apache.org/foundation/glossary.html#Codebase> in
question. If the R-T-C
<http://www.apache.org/foundation/glossary.html#ReviewThenCommit>
commit policy is in effect, a veto prevents the change from being
made. In either the R-T-C or C-T-R
<http://www.apache.org/foundation/glossary.html#CommitThenReview>
environments, a veto applied to a change that has already been made
forces it to be reverted. Vetos may not be overridden nor voted
down, and only cease to apply when the committer who issued the veto
withdraws it. All vetos /must/ be accompanied by a valid technical
justification; a veto without such a justification is invalid. Vetos
only apply to code changes; they do not apply to procedural issues
such as software releases.
Therefore, your veto is invalid.
--
Trustin Lee - Principal Software Engineer, JBoss, Red Hat
--
what we call human nature is actually human habit
--
http://gleamynode.net/
