Re: Remove Useless Comments
On Jul 18, 2007, at 11:17, Vincent Hennebert wrote: Only the trunk. They are not functional changes so don't need to figure in the 0.94 release. Only (urgent) bug corrections should be merged in the branch now. OK. BTW, the proper use of inheritDoc seems to be like the following: /** [EMAIL PROTECTED] */ public void someMethod() and not /** @inheritDoc SuperClass#someMethod() */ public void someMethod() Javadoc doesn't seem to be troubled by the latter and gives the same result, but Eclipse only displays "SuperClass#someMethod()" in the tooltip in this case. Not really an improvement :-( Can you check this? No problem. A regexp like "@inheritDoc\s(.*?)(?=\s)" (replace with "[EMAIL PROTECTED] \}") seems to do the trick. Some 1750 occurrences in 425 files. Imagine replacing all of them manually... Cheers Andreas
Re: Remove Useless Comments
Hi Andreas, Andreas L Delmelle a écrit : > On Jul 14, 2007, at 15:59, Vincent Hennebert wrote: > > Vincent > >> Andreas L Delmelle a écrit : >>> >>> Tested locally, and is OK here. If you'd like, I can run a sanity diff >>> later tonight, and commit the changes sometime tomorrow. >> >> Thanks, Andreas. We should perhaps just wait a couple of days, just to >> be sure everybody's ok with that? > > Concerning these javadoc changes I'm going to commit tomorrow > (Wednesday) evening: > Do I apply the changes to the release branch, to the trunk or both? Only the trunk. They are not functional changes so don't need to figure in the 0.94 release. Only (urgent) bug corrections should be merged in the branch now. BTW, the proper use of inheritDoc seems to be like the following: /** [EMAIL PROTECTED] */ public void someMethod() and not /** @inheritDoc SuperClass#someMethod() */ public void someMethod() Javadoc doesn't seem to be troubled by the latter and gives the same result, but Eclipse only displays "SuperClass#someMethod()" in the tooltip in this case. Not really an improvement :-( Can you check this? Thanks, Vincent
Re: Remove Useless Comments
On Jul 14, 2007, at 15:59, Vincent Hennebert wrote: Vincent Andreas L Delmelle a écrit : Tested locally, and is OK here. If you'd like, I can run a sanity diff later tonight, and commit the changes sometime tomorrow. Thanks, Andreas. We should perhaps just wait a couple of days, just to be sure everybody's ok with that? Concerning these javadoc changes I'm going to commit tomorrow (Wednesday) evening: Do I apply the changes to the release branch, to the trunk or both? Cheers Andreas
Re: Remove Useless Comments
Andreas L Delmelle wrote: The javadocs build with only one small warning concerning @todo tags somewheres (which I don't take to be a major issue) The @todo is a custom tag, which are available with Java 1.4. I thought I added a definition for this to the javadoc task in build.xml. In principle we could use @todo tags to generate a todo document for the web site, if we hadn't already a wiki page for this. J.Pietschmann
Re: Remove Useless Comments
On Jul 15, 2007, at 14:17, Andreas L Delmelle wrote: On Jul 14, 2007, at 21:22, Andreas L Delmelle wrote: On Jul 14, 2007, at 15:59, Vincent Hennebert wrote: Thanks, Andreas. We should perhaps just wait a couple of days, just to be sure everybody's ok with that? Indeed, let's give everyone a chance to react before committing. Will have to go over them one by one and decide which ones to replace, I guess. :/ FYI: just finished this task, and it's ready to be committed now. The javadocs build with only one small warning concerning @todo tags somewheres (which I don't take to be a major issue) If no objections are raised by Wednesday evening GMT+1, I'll go ahead and commit. Cheers Andreas
Re: Remove Useless Comments
On Jul 14, 2007, at 21:22, Andreas L Delmelle wrote: On Jul 14, 2007, at 15:59, Vincent Hennebert wrote: Thanks, Andreas. We should perhaps just wait a couple of days, just to be sure everybody's ok with that? Indeed, let's give everyone a chance to react before committing. FWIW: just tried rebuilding the javadocs, and it will take some more work anyway. There are places where @see is no problem, but @inheritDoc cannot be used (class docs, constructors...) Will have to go over them one by one and decide which ones to replace, I guess. :/ OTOH, I'll also take the liberty of correcting a few other glitches in the docs, while I'm at it (mainly some incorrect @params and @returns). Later Andreas
Re: Remove Useless Comments
On Jul 14, 2007, at 15:59, Vincent Hennebert wrote: Andreas L Delmelle a écrit : A script would not even be needed. An editor like jEdit will let you S&R every @see with an @inheritDoc for all .java files in the src/java/org/apache/fop directory and subdirectories... Tested locally, and is OK here. If you'd like, I can run a sanity diff later tonight, and commit the changes sometime tomorrow. Thanks, Andreas. We should perhaps just wait a couple of days, just to be sure everybody's ok with that? Indeed, let's give everyone a chance to react before committing. Cheers Andreas
Re: Remove Useless Comments
Andreas L Delmelle a écrit : > On Jul 14, 2007, at 13:27, Vincent Hennebert wrote: >> J.Pietschmann a écrit : >>> I think of JavaDoc as a sort of compile time feature. I don't think >>> there's still a reason to generate the JavaDocs with a JDK version >>> older than 1.5. It's the byte code which should run in an 1.3 >>> environment, not the HTML'd docs. >> >> +1000. If nobody objects, from now on, I'll systematically replace such >> comments with @inheritDoc whenever I have the opportunity. >> Perhaps even a small script... > > A script would not even be needed. An editor like jEdit will let you S&R > every @see with an @inheritDoc for all .java files in the > src/java/org/apache/fop directory and subdirectories... > > Tested locally, and is OK here. If you'd like, I can run a sanity diff > later tonight, and commit the changes sometime tomorrow. Thanks, Andreas. We should perhaps just wait a couple of days, just to be sure everybody's ok with that? Vincent
Re: Remove Useless Comments
On Jul 14, 2007, at 13:27, Vincent Hennebert wrote: J.Pietschmann a écrit : Jeremias Maerki wrote: Yes, inheritDoc would be the right way, as long as we're on Java 1.4.2 and later (feature not available in 1.3, severly buggy in 1.4.0/1.4.1. I would have switched a long time ago if we weren't still on 1.3. I think of JavaDoc as a sort of compile time feature. I don't think there's still a reason to generate the JavaDocs with a JDK version older than 1.5. It's the byte code which should run in an 1.3 environment, not the HTML'd docs. +1000. If nobody objects, from now on, I'll systematically replace such comments with @inheritDoc whenever I have the opportunity. Perhaps even a small script... A script would not even be needed. An editor like jEdit will let you S&R every @see with an @inheritDoc for all .java files in the src/ java/org/apache/fop directory and subdirectories... Tested locally, and is OK here. If you'd like, I can run a sanity diff later tonight, and commit the changes sometime tomorrow. Cheers Andreas
Re: Remove Useless Comments
J.Pietschmann a écrit : > Jeremias Maerki wrote: >> Yes, inheritDoc would be the right way, as long as we're on Java 1.4.2 >> and later (feature not available in 1.3, severly buggy in 1.4.0/1.4.1. I >> would have switched a long time ago if we weren't still on 1.3. > > I think of JavaDoc as a sort of compile time feature. I don't think > there's still a reason to generate the JavaDocs with a JDK version > older than 1.5. It's the byte code which should run in an 1.3 > environment, not the HTML'd docs. +1000. If nobody objects, from now on, I'll systematically replace such comments with @inheritDoc whenever I have the opportunity. Perhaps even a small script... Vincent
Re: Remove Useless Comments
Jeremias Maerki wrote: Yes, inheritDoc would be the right way, as long as we're on Java 1.4.2 and later (feature not available in 1.3, severly buggy in 1.4.0/1.4.1. I would have switched a long time ago if we weren't still on 1.3. I think of JavaDoc as a sort of compile time feature. I don't think there's still a reason to generate the JavaDocs with a JDK version older than 1.5. It's the byte code which should run in an 1.3 environment, not the HTML'd docs. J.Pietschmann
Re: Remove Useless Comments [Re: svn commit: r555684 - /xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java]
On Jul 13, 2007, at 12:09, Vincent Hennebert wrote: Nothing related with (and against) the original change, but I take this one as an opportunity to launch the discussion. I've been having this in my head for a while. Yes, I seem to remember the point being raised earlier... and to be honest, I don't really see the use either. It's just (very understandable ;)) laziness, I guess: add one * to Eclipse's default comment when adding an override, and you get precisely that pseudo- javadoc. Cheers Andreas
Re: Remove Useless Comments
Yes, inheritDoc would be the right way, as long as we're on Java 1.4.2 and later (feature not available in 1.3, severly buggy in 1.4.0/1.4.1. I would have switched a long time ago if we weren't still on 1.3. On 13.07.2007 15:49:58 Max Berger wrote: > Dear Fop-devs, > > as always, I have no say in this, but what I usually do is to use > > /** [EMAIL PROTECTED] */ > > This works really well, if the method inherits from a class / interface > which is also present in the same codebase: Checkstyle is happy, and so > is JavaDoc. Also, JavaDoc gives a warning if a method uses inheritDoc, > but does not implement / override a method (a way of detecting renames > in superclasses) > > For some more discussion on this matter, see [1] > > [1] > http://mail-archives.apache.org/mod_mbox/jackrabbit-dev/200503.mbox/[EMAIL > PROTECTED] > > hth > > Max > > Vincent Hennebert schrieb: > > Hi, > > > > Nothing related with (and against) the original change, but I take this > > one as an opportunity to launch the discussion. I've been having this in > > my head for a while. > > > >> - /** @see org.apache.fop.layoutmgr.LayoutManager#initialize() */ > >> +/** @see org.apache.fop.layoutmgr.LayoutManager#initialize() */ > > > > I'd like to suggest to remove such comments every time there's an > > opportunity. They are useless for javadoc which is able to retrieve the > > comment from the redefined method. They are painful when discovering > > code in Eclipse because when we hover a method call, we get that comment > > instead of the real one, which Eclipse also is able to retrieve. > > > > The only reason I can think of for such a comment is to make checkstyle > > happy. But I don't think this is a solution. Checkstyle should be aware > > that in Java redefined methods inherit their javadoc from the original > > one, and shouldn't complain in this case. So here it's checkstyle that > > is wrong. > > > > Anyway, there are already zillions of checkstyle warnings in the current > > codebase, so I guess we can live with a few more. > > > > > > WDYT? > > Vincent > > > Jeremias Maerki
Re: Remove Useless Comments
Dear Fop-devs, as always, I have no say in this, but what I usually do is to use /** [EMAIL PROTECTED] */ This works really well, if the method inherits from a class / interface which is also present in the same codebase: Checkstyle is happy, and so is JavaDoc. Also, JavaDoc gives a warning if a method uses inheritDoc, but does not implement / override a method (a way of detecting renames in superclasses) For some more discussion on this matter, see [1] [1] http://mail-archives.apache.org/mod_mbox/jackrabbit-dev/200503.mbox/[EMAIL PROTECTED] hth Max Vincent Hennebert schrieb: > Hi, > > Nothing related with (and against) the original change, but I take this > one as an opportunity to launch the discussion. I've been having this in > my head for a while. > >> - /** @see org.apache.fop.layoutmgr.LayoutManager#initialize() */ >> +/** @see org.apache.fop.layoutmgr.LayoutManager#initialize() */ > > I'd like to suggest to remove such comments every time there's an > opportunity. They are useless for javadoc which is able to retrieve the > comment from the redefined method. They are painful when discovering > code in Eclipse because when we hover a method call, we get that comment > instead of the real one, which Eclipse also is able to retrieve. > > The only reason I can think of for such a comment is to make checkstyle > happy. But I don't think this is a solution. Checkstyle should be aware > that in Java redefined methods inherit their javadoc from the original > one, and shouldn't complain in this case. So here it's checkstyle that > is wrong. > > Anyway, there are already zillions of checkstyle warnings in the current > codebase, so I guess we can live with a few more. > > > WDYT? > Vincent signature.asc Description: OpenPGP digital signature
Remove Useless Comments [Re: svn commit: r555684 - /xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java]
Hi, Nothing related with (and against) the original change, but I take this one as an opportunity to launch the discussion. I've been having this in my head for a while. > Modified: > > xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java > > Modified: > xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java > URL: > http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java?view=diff&rev=555684&r1=555683&r2=555684 > == > --- > xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java > (original) > +++ > xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java > Thu Jul 12 09:24:27 2007 > @@ -84,7 +84,7 @@ > private Block fobj; > private boolean isFirstInBlock; > > - /** @see org.apache.fop.layoutmgr.LayoutManager#initialize() */ > +/** @see org.apache.fop.layoutmgr.LayoutManager#initialize() */ I'd like to suggest to remove such comments every time there's an opportunity. They are useless for javadoc which is able to retrieve the comment from the redefined method. They are painful when discovering code in Eclipse because when we hover a method call, we get that comment instead of the real one, which Eclipse also is able to retrieve. The only reason I can think of for such a comment is to make checkstyle happy. But I don't think this is a solution. Checkstyle should be aware that in Java redefined methods inherit their javadoc from the original one, and shouldn't complain in this case. So here it's checkstyle that is wrong. Anyway, there are already zillions of checkstyle warnings in the current codebase, so I guess we can live with a few more. WDYT? Vincent
