You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-commits@xmlgraphics.apache.org by ad...@apache.org on 2007/07/12 18:24:28 UTC
svn commit: r555684 -
/xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java
Author: adelmelle
Date: Thu Jul 12 09:24:27 2007
New Revision: 555684
URL: http://svn.apache.org/viewvc?view=rev&rev=555684
Log:
Completion of the previous two small patches: modified and corrected javadoc comments
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() */
public void initialize() {
textAlignment = fobj.getTextAlign();
textAlignmentLast = fobj.getTextAlignLast();
@@ -638,7 +638,6 @@
/**
* Phase 1 of Knuth algorithm: Collect all inline Knuth elements before determining line breaks.
* @param context the LayoutContext
- * @param availIPD available IPD for line (should be removed!)
*/
private void collectInlineKnuthElements(LayoutContext context) {
LayoutContext inlineLC = new LayoutContext(context);
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org
Re: Remove Useless Comments
Posted by "J.Pietschmann" <j3...@yahoo.de>.
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
Posted by Andreas L Delmelle <a_...@pandora.be>.
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:
>>> <snip />
>>> 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.
>
> <snip />
> 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
Posted by Andreas L Delmelle <a_...@pandora.be>.
On Jul 14, 2007, at 21:22, Andreas L Delmelle wrote:
> On Jul 14, 2007, at 15:59, Vincent Hennebert wrote:
>> <snip />
>> 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
Posted by Andreas L Delmelle <a_...@pandora.be>.
On Jul 14, 2007, at 15:59, Vincent Hennebert wrote:
> Andreas L Delmelle a écrit :
>> <snip />
>> 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
Posted by Andreas L Delmelle <a_...@pandora.be>.
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:
> /** {@inheritDoc} */
> 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 "\{@inheritDoc
\}") seems to do the trick.
Some 1750 occurrences in 425 files. Imagine replacing all of them
manually...
Cheers
Andreas
Re: Remove Useless Comments
Posted by Vincent Hennebert <vi...@anyware-tech.com>.
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:
/** {@inheritDoc} */
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
Posted by Andreas L Delmelle <a_...@pandora.be>.
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
Posted by Vincent Hennebert <vi...@anyware-tech.com>.
Andreas L Delmelle a écrit :
> On Jul 14, 2007, at 13:27, Vincent Hennebert wrote:
>> J.Pietschmann a écrit :
<snip/>
>>> 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
Posted by Andreas L Delmelle <a_...@pandora.be>.
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
Posted by Vincent Hennebert <vi...@anyware-tech.com>.
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
Posted by "J.Pietschmann" <j3...@yahoo.de>.
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
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
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
>
> /** {@inheritDoc} */
>
> 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/%3C8be7318805031807302d6f6906@mail.gmail.com%3E
>
> 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 [Re: svn commit: r555684 - /xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java]
Posted by Andreas L Delmelle <a_...@pandora.be>.
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
Posted by Max Berger <ma...@berger.name>.
Dear Fop-devs,
as always, I have no say in this, but what I usually do is to use
/** {@inheritDoc} */
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/%3C8be7318805031807302d6f6906@mail.gmail.com%3E
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
Remove Useless Comments [Re: svn commit: r555684 - /xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LineLayoutManager.java]
Posted by Vincent Hennebert <vi...@anyware-tech.com>.
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