On Fri, May 23, 2008 at 3:39 AM, 이희승 (Trustin Lee) <[EMAIL PROTECTED]> wrote:
> 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. >> > > > 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. Sorry that's not the case and you need to respect Emmanuel's veto. You cannot sit there discussing this ad nausium and brushing aside his concerns which I describe below. Otherwise you make this PMC utterly useless. Let's not make it into a bunch of powerless Trustin cheerleaders. I know this whole Javadoc thing sounds rediculous but Mark Webb said well that we're loosing the real point being made by Emmanuel. You're committing code without Javadocs quite often. This is making it harder to get more people into the core. In the old days of Avalon a veto was once cast over a Javadoc change and it had to be respected. Those who faught it weakened the ability of the TLP to survive. This could have been a descent conversation, but once again was degraded into a pissing match. Could we be a little less obstinate with one another over these relatively non-issues. Both you guys have some points. Trustin it also does not help reeming people about their "lack of action". Emmanuel has taken action and is involved in our community addressing various matters. It's not all about the code although he's in there trying to get familiar. At Avalon, the biggest problem was that some people thought it was only about the code. Could you please stop biting folks like this? Your going to start getting more vetos until you take absolutely every precaution mandated to make the code as easy to pick up by others as possible. That's to protect the project and not to attack you. Please understand this. Alex P.S. I thought we had a great converstation over skype and it was clear how and why there were issues but the same thing is occuring again systemically: maybe we need to have another private session?
