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 vh...@apache.org on 2010/08/27 15:31:41 UTC
svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop:
area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/
hyphenation/ layoutmgr/ layoutmgr/inline/ layoutmgr/table/
Author: vhennebert
Date: Fri Aug 27 13:31:41 2010
New Revision: 990148
URL: http://svn.apache.org/viewvc?rev=990148&view=rev
Log:
Replaced @asf.todo with normal TODO comment
Modified:
xmlgraphics/fop/trunk/src/java/org/apache/fop/area/DestinationData.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FOPropertyMapping.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FObj.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Footnote.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Leader.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/ListItem.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Marker.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/MultiCase.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/table/TableAndCaption.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/pagination/PageSequence.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/properties/CharacterProperty.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/ByteVector.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/HyphenationException.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/FlowLayoutManager.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/LayoutException.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LeafNodeLayoutManager.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLastLayoutManager.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLayoutManager.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableAndCaptionLayoutManager.java
xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableCaptionLayoutManager.java
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/area/DestinationData.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/area/DestinationData.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/area/DestinationData.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/area/DestinationData.java Fri Aug 27 13:31:41 2010
@@ -98,7 +98,7 @@ public class DestinationData extends Abs
* object that corresponds to the IDRef
*
* {@inheritDoc} List)
- * @asf.todo check to make sure it works if multiple bookmark-items
+ * TODO check to make sure it works if multiple bookmark-items
* have the same idref
*/
public void resolveIDRef(String id, List pages) {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FOPropertyMapping.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FOPropertyMapping.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FOPropertyMapping.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FOPropertyMapping.java Fri Aug 27 13:31:41 2010
@@ -72,7 +72,7 @@ import org.apache.fop.fo.properties.XMLL
* This class creates and returns an array of Property.Maker instances
* indexed by the PR_* propId from Constants.java.
*
- * @asf.todo Check multi-threading safety of the statics below
+ * TODO Check multi-threading safety of the statics below
*/
public final class FOPropertyMapping implements Constants {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FObj.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FObj.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FObj.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/FObj.java Fri Aug 27 13:31:41 2010
@@ -255,7 +255,7 @@ public abstract class FObj extends FONod
/**
* Check if this formatting object generates reference areas.
* @return true if generates reference areas
- * @asf.todo see if needed
+ * TODO see if needed
*/
public boolean generatesReferenceAreas() {
return false;
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Footnote.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Footnote.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Footnote.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Footnote.java Fri Aug 27 13:31:41 2010
@@ -76,9 +76,9 @@ public class Footnote extends FObj {
/**
* {@inheritDoc}
* <br>XSL Content Model: (inline,footnote-body)
- * @asf.todo implement additional constraint: A fo:footnote is not permitted
+ * TODO implement additional constraint: A fo:footnote is not permitted
* to have a fo:float, fo:footnote, or fo:marker as a descendant.
- * @asf.todo implement additional constraint: A fo:footnote is not
+ * TODO implement additional constraint: A fo:footnote is not
* permitted to have as a descendant a fo:block-container that
* generates an absolutely positioned area.
*/
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Leader.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Leader.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Leader.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Leader.java Fri Aug 27 13:31:41 2010
@@ -30,7 +30,7 @@ import org.apache.fop.fo.properties.Leng
* <code>fo:leader</code></a> object.
* The main property of <code>fo:leader</code> is leader-pattern.
* The following patterns are treated: rule, space, dots and use-content.
- * @asf.todo implement validateChildNode()
+ * TODO implement validateChildNode()
*/
public class Leader extends InlineLevel {
// The value of properties relevant for fo:leader.
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/ListItem.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/ListItem.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/ListItem.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/ListItem.java Fri Aug 27 13:31:41 2010
@@ -119,7 +119,7 @@ public class ListItem extends FObj imple
/**
* {@inheritDoc}
- * @asf.todo see if can/should rely on base class for this
+ * TODO see if can/should rely on base class for this
* (i.e., add to childNodes instead)
*/
public void addChildNode(FONode child) {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Marker.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Marker.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Marker.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/Marker.java Fri Aug 27 13:31:41 2010
@@ -110,7 +110,7 @@ public class Marker extends FObjMixed {
* <br><i>Additionally: "An fo:marker may contain any formatting objects that
* are permitted as a replacement of any fo:retrieve-marker that retrieves
* the fo:marker's children."</i>
- * @asf.todo implement "additional" constraint, possibly within fo:retrieve-marker
+ * TODO implement "additional" constraint, possibly within fo:retrieve-marker
*/
protected void validateChildNode(Locator loc, String nsURI, String localName)
throws ValidationException {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/MultiCase.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/MultiCase.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/MultiCase.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/MultiCase.java Fri Aug 27 13:31:41 2010
@@ -27,7 +27,7 @@ import org.apache.fop.fo.PropertyList;
/**
* Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_multi-case">
* <code>fo:multi-case</code></a> object.
- * @asf.todo implement validateChildNode()
+ * TODO implement validateChildNode()
*/
public class MultiCase extends FObj {
// The value of properties relevant for fo:multi-case.
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/table/TableAndCaption.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/table/TableAndCaption.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/table/TableAndCaption.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/flow/table/TableAndCaption.java Fri Aug 27 13:31:41 2010
@@ -30,7 +30,7 @@ import org.apache.fop.fo.ValidationExcep
/**
* Class modelling the <a href="http://www.w3.org/TR/xsl/#fo_table-and-caption">
* <code>fo:table-and-caption</code></a> property.
- * @asf.todo needs implementation
+ * TODO needs implementation
*/
public class TableAndCaption extends FObj /*implements BreakPropertySet*/ {
// The value of properties relevant for fo:table-and-caption.
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/pagination/PageSequence.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/pagination/PageSequence.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/pagination/PageSequence.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/pagination/PageSequence.java Fri Aug 27 13:31:41 2010
@@ -151,7 +151,7 @@ public class PageSequence extends Abstra
/**
* {@inheritDoc}
- * @asf.todo see if addChildNode() should also be called for fo's other than
+ * TODO see if addChildNode() should also be called for fo's other than
* fo:flow.
*/
public void addChildNode(FONode child) throws FOPException {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/properties/CharacterProperty.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/properties/CharacterProperty.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/properties/CharacterProperty.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/fo/properties/CharacterProperty.java Fri Aug 27 13:31:41 2010
@@ -24,7 +24,7 @@ import org.apache.fop.fo.PropertyList;
/**
* Superclass for properties that wrap a character value
- * @asf.todo convert character value to int in order to denote unicode scalar value
+ * TODO convert character value to int in order to denote unicode scalar value
* instead of a single UTF-16 code element
*/
public final class CharacterProperty extends Property {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/ByteVector.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/ByteVector.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/ByteVector.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/ByteVector.java Fri Aug 27 13:31:41 2010
@@ -69,7 +69,7 @@ public class ByteVector implements Seria
/**
* Construct byte vector instance.
* @param a byte array to use
- * @asf.todo should n should be initialized to a.length to be consistent with
+ * TODO should n should be initialized to a.length to be consistent with
* CharVector behavior? [GA]
*/
public ByteVector(byte[] a) {
@@ -82,7 +82,7 @@ public class ByteVector implements Seria
* Construct byte vector instance.
* @param a byte array to use
* @param capacity initial block size
- * @asf.todo should n should be initialized to a.length to be consistent with
+ * TODO should n should be initialized to a.length to be consistent with
* CharVector behavior? [GA]
*/
public ByteVector(byte[] a, int capacity) {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/HyphenationException.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/HyphenationException.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/HyphenationException.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/hyphenation/HyphenationException.java Fri Aug 27 13:31:41 2010
@@ -22,7 +22,7 @@ package org.apache.fop.hyphenation;
/**
* An hyphenation exception.
* @author Carlos Villegas <ca...@uniscope.co.jp>
- * @asf.todo Derive from FOPException
+ * TODO Derive from FOPException
*/
public class HyphenationException extends Exception {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/FlowLayoutManager.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/FlowLayoutManager.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/FlowLayoutManager.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/FlowLayoutManager.java Fri Aug 27 13:31:41 2010
@@ -36,7 +36,7 @@ import org.apache.fop.fo.pagination.Flow
* Its parent LM is the PageSequenceLayoutManager.
* This LM is responsible for getting columns of the appropriate size
* and filling them with block-level areas generated by its children.
- * @asf.todo Reintroduce emergency counter (generate error to avoid endless loop)
+ * TODO Reintroduce emergency counter (generate error to avoid endless loop)
*/
public class FlowLayoutManager extends BlockStackingLayoutManager
implements BlockLevelLayoutManager {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/LayoutException.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/LayoutException.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/LayoutException.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/LayoutException.java Fri Aug 27 13:31:41 2010
@@ -29,7 +29,7 @@ import org.apache.fop.events.EventExcept
* Exception thrown by FOP if an unrecoverable layout error occurs. An example: An area overflows
* a viewport that has overflow="error-if-overflow".
*
- * @asf.todo Discuss if this should become a checked exception.
+ * TODO Discuss if this should become a checked exception.
*/
public class LayoutException extends RuntimeException {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LeafNodeLayoutManager.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LeafNodeLayoutManager.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LeafNodeLayoutManager.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/LeafNodeLayoutManager.java Fri Aug 27 13:31:41 2010
@@ -48,7 +48,7 @@ import org.apache.fop.traits.MinOptMax;
* an exception to this rule.)
* This class can be extended to handle the creation and adding of the
* inline area.
- * @asf.todo [GA] replace use of hungarian notation with normalized java naming
+ * TODO [GA] replace use of hungarian notation with normalized java naming
*/
public abstract class LeafNodeLayoutManager extends AbstractLayoutManager
implements InlineLevelLayoutManager {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLastLayoutManager.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLastLayoutManager.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLastLayoutManager.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLastLayoutManager.java Fri Aug 27 13:31:41 2010
@@ -37,7 +37,7 @@ public class PageNumberCitationLastLayou
* Constructor
*
* @param node the formatting object that creates this area
- * @asf.todo better retrieval of font info
+ * TODO better retrieval of font info
*/
public PageNumberCitationLastLayoutManager(PageNumberCitationLast node) {
super(node);
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLayoutManager.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLayoutManager.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLayoutManager.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/inline/PageNumberCitationLayoutManager.java Fri Aug 27 13:31:41 2010
@@ -35,7 +35,7 @@ public class PageNumberCitationLayoutMan
* Constructor
*
* @param node the formatting object that creates this area
- * @asf.todo better retrieval of font info
+ * TODO better retrieval of font info
*/
public PageNumberCitationLayoutManager(PageNumberCitation node) {
super(node);
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableAndCaptionLayoutManager.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableAndCaptionLayoutManager.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableAndCaptionLayoutManager.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableAndCaptionLayoutManager.java Fri Aug 27 13:31:41 2010
@@ -33,7 +33,7 @@ import org.apache.fop.layoutmgr.Position
* The caption contains blocks that are positioned next to the
* table on the caption side.
* The caption blocks have an implicit keep with the table.
- * @asf.todo Implement getNextKnuthElements()
+ * TODO Implement getNextKnuthElements()
*/
public class TableAndCaptionLayoutManager extends BlockStackingLayoutManager {
Modified: xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableCaptionLayoutManager.java
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableCaptionLayoutManager.java?rev=990148&r1=990147&r2=990148&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableCaptionLayoutManager.java (original)
+++ xmlgraphics/fop/trunk/src/java/org/apache/fop/layoutmgr/table/TableCaptionLayoutManager.java Fri Aug 27 13:31:41 2010
@@ -31,7 +31,7 @@ import org.apache.fop.layoutmgr.Position
* LayoutManager for a table-caption FO.
* The table caption contains blocks that are placed beside the
* table.
- * @asf.todo Implement getNextKnuthElements()
+ * TODO Implement getNextKnuthElements()
*/
public class TableCaptionLayoutManager extends BlockStackingLayoutManager {
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org
Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop:
area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/
layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by "J.Pietschmann" <j3...@yahoo.de>.
On 02.09.2010 12:14, Glenn Adams wrote:
> also the doclet options to permit use of @todo without warnings. I could try
> to experiment some to see if that is feasible, then we could return to the
> former usage of @todo.
Javadoc 1.5 or later can be passed a command line option defining
additional tokens to accept:
http://download.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#tag
I vaguely remember to have had it working in my local build.xml some
times ago.
J.Pietschmann
Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop:
area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/
layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by Glenn Adams <gl...@skynav.com>.
On Thu, Sep 2, 2010 at 6:04 PM, Jeremias Maerki <de...@jeremias-maerki.ch>wrote:
> I'm not sure we have the tooling to make sure noone
> uses @todo.
>
Actually, checkstyle 5.1 will report warnings for any use of a non-standard
tag that is not qualified with a dotted prefix. Also the standard Doclet in
recent JDKs will complain as well. So if committers run checkstyle and
javadocs targets before committing, we should be able to keep this usage
out.
On the other hand, it may be possible to fine tune the checkstyle rules and
also the doclet options to permit use of @todo without warnings. I could try
to experiment some to see if that is feasible, then we could return to the
former usage of @todo.
G.
Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop: area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/ layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
Just to add my 0.05 CHF: I normally use @todo when adding TODOs as part
of a method or class comment and I use //TODO inline. That's because
plain "TODO" lets the full text bleed into the Javadocs which is
certainly something we don't want. See for example:
org.apache.fop.area.DestinationData.resolveIDRef()
------
public void resolveIDRef(java.lang.String id,
java.util.List pages)
Resolves the idref of this object by getting the PageViewport object that corresponds to the IDRef This method allows the Resolvable object to resolve one of its unresolved idrefs with the actual set of PageViewports containing the target ID. The Resolvable object initially identifies to the AreaTreeHandler which idrefs it needs resolved. After the idrefs are resolved, the ATH calls this method to allow the Resolvable object to update itself with the PageViewport information. List) TODO check to make sure it works if multiple bookmark-items have the same idref
Specified by:
resolveIDRef in interface Resolvable
Parameters:
id - an ID matching one of the Resolvable object's unresolved idref's.
pages - the list of PageViewports with the given ID
------
Or in org.apache.xmlgraphics.fonts.Glyphs:
------
public static final java.lang.String glyphToString(java.lang.String name)
Deprecated. User getUnicodeCodePointsForGlyphName instead. This method only returns the first Unicode code point it finds.
Return the glyphname from a string, eg, glyphToString("\\") returns "backslash"
Parameters:
name - glyph to evaluate
Returns:
the name of the glyph TODO: javadocs for glyphToString and stringToGlyph are confused
------
I think we may still have various occurences where an empty line instead
of a <br> or <p> was used to delimit a paragraph which sometimes leads
to odd looking Javadocs. (but that's a different topic)
I'm not particularly in favor of @asf.todo because I'm sure most people
will instinctively rather use @todo and have to make an effort to
remember @asf.todo. I'm not sure we have the tooling to make sure noone
uses @todo.
I've checked a few other ASF projects' source code to see what they do.
A few have "TODO" in their Javadocs comments with the side-effect
described above. Others, like Felix, don't put their TODO's in the
Javadoc comment at all but use this pattern:
------
/**
* This class caches conditions instances by their infos. Furthermore, it allows
* to eval postponed condition permission tuples as per spec (see 9.45).
*/
// TODO: maybe use bundle events instead of soft/weak references.
public final class Conditions
------
That would also be safe. Actual Javadoc comments like @todo are
relatively few.
Based on these findings, I recommend we eventually remove TODOs and
@todo from the Javadoc comments and use //TODO comments exclusively.
Eclipse can handle all TODOs correctly by default. And Javadocs don't
get polluted. I believe that would pretty much address everyone's
concerns.
On 31.08.2010 13:33:25 Vincent Hennebert wrote:
> Hi,
>
> I just thought I would homogenize our usage of todo tags and match what
> seems to be the de facto standard (“TODO”) among current committers.
> Most @todo indeed come from very old commits. I didn’t realise that
> javadoc could do something with them, which is why that looked to me
> like a minor change that wasn’t needing prior discussion. Sorry about
> that.
>
> Ok, so there is something that can be done out of @todo tags in javadoc
> comments. Now, having to use our own namespaced version is unfortunate
> and looks overkill to me. Just to have a slightly better formatted
> javadoc? Are such comments of any use to users of the API anyway? Most
> of them rather look like pure internal development issues and should
> probably not even appear in the javadoc.
>
> Also, while @todo tags can be indexed, modern IDEs can index plain TODO
> tokens as well, so that reduces the advantage of @asf.todo IMO.
>
> If there are strong feelings against the removal of @asf.todo, I’ll
> revert the change. Otherwise, I’ll actually complete it by removing the
> definition of the custom tag in build.xml, which I hadn’t spotted.
>
> Vincent
>
>
> Simon Pepping wrote:
> > It would indeed have been better to first have a discussion and then
> > make the change. @asf.todo is specific enough that we could have
> > changed it at any time. That said, Glenn's change was also made
> > without a discussion. My javadoc does not complain about the @todo
> > tag, and I had not understood that this was a motivation.
> >
> > The javadoc documentation (of my sun-java6-jdk) is not clear about
> > this topic, and uses @todo liberally in its section about the -tag
> > option. Its most informative paragraph is this:
> >
> > "Avoiding Conflicts - If you want to slice out your own namespace, you
> > can use a dot-separated naming convention similar to that used for
> > packages: com.mycompany.todo. Sun will continue to create standard
> > tags whose names do not contain dots. Any tag you create will override
> > the behavior of a tag by the same name defined by Sun. In other words,
> > if you create a tag or taglet @todo, it will always have the same
> > behavior you define, even if Sun later creates a standard tag of the
> > same name."
> >
> > which does not even go so far as to discourage the @todo tag. It is
> > also not clear how a todo tag would be a specific asf tag, different
> > from the todo tag of any other organization. Everybody uses todo and
> > means the same with it.
> >
> > Using the widely recognized TODO keyword circumvents the tag question
> > altogether, but is outdated since the advent of tags.
> >
> > Let us discuss this and not waste effort on undoing each other's
> > expression of their point of view. Let us also not forget that working
> > in a team requires compromises; the code will never match your own
> > conventions and preferences as precisely as code in your very own
> > project. This is more so in an open project with a long history and a
> > large set of authors.
> >
> > Simon
> >
> > On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote:
> >> Vincent,
> >>
> >> Could you explain your rationale for this change? Originally, these were all
> >> marked with a non-standard '@todo' javadoc tag, which javadoc complained
> >> about, indicating that for "non-standard" tags, there should be at least one
> >> '.' present in the tag name. I had fixed this by adding the "asf." prefix,
> >> which still allowed tracking these in javadoc more easily. However, your
> >> change now removes the utility of the tag.
> >>
> >> On a more general point, wouldn't it be more useful to have a discussion
> >> about stylistic changes prior to implementing them? Just so we can get on
> >> the same page?
> >>
> >> Regards,
> >> Glenn
> >>
> >> On Fri, Aug 27, 2010 at 9:31 PM, <vh...@apache.org> wrote:
> >>
> >>> Author: vhennebert
> >>> Date: Fri Aug 27 13:31:41 2010
> >>> New Revision: 990148
> >>>
> >>> URL: http://svn.apache.org/viewvc?rev=990148&view=rev
> >>> Log:
> >>> Replaced @asf.todo with normal TODO comment
> >>>
> >>>
> >
Jeremias Maerki
RE: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop: area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/ layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by Eric Douglas <ed...@blockhouse.com>.
I agree. TODO should be something for the developer of the objects.
Javadoc should be something for the developer of something which
implements those objects. They don't really belong together. I'd keep
separate documentation if you want to let the implementing programmer
know what the developing programmer is planning to do next. I think
taking the @ off the TODO makes sense.
-----Original Message-----
From: Jeremias Maerki [mailto:dev@jeremias-maerki.ch]
Sent: Wednesday, September 08, 2010 8:19 AM
To: fop-dev@xmlgraphics.apache.org
Subject: Re: TODO tag [was: Re: svn commit: r990148 - in
/xmlgraphics/fop/trunk/src/java/org/apache/fop: area/ fo/ fo/flow/
fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/ layoutmgr/
layoutmgr/inline/ layoutmgr/table/]
+1!
On 08.09.2010 13:02:29 Vincent Hennebert wrote:
> Ok, let me summarise this:
>
> * a @[asf.]todo tag marginally improves the formatting of a javadoc
> comment
> * nobody really likes the idea of using a namespaced version of todo
> (@asf.todo)
> * it is possible to tweak Checkstyle and the javadoc command to enable
> the use of @todo
>
> That said:
> * todo statements generally have little to do (sic) in a javadoc
comment
> anyway
> * TODO keywords are easily indexable by modern IDEs
>
> Jeremias recommends the Felix way: using //TODO comments below the
> javadoc. I'm also strongly in favour of this convention. OTOH, if I'm
> correct nobody strongly feels that @todo tags are necessary.
>
> So I think we have a consensus:
> * from now on we stop using @todo in favour of the Felix convention; *
> we will progressively remove TODO statements from javadoc comments and
> move them below in their own Java // comments * I remove the
> definition of the custom tag from build.xml
>
> Let me know if I missed anything.
>
> Thanks,
> Vincent
<snip/>
Jeremias Maerki
Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop: area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/ layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
+1!
On 08.09.2010 13:02:29 Vincent Hennebert wrote:
> Ok, let me summarise this:
>
> • a @[asf.]todo tag marginally improves the formatting of a javadoc
> comment
> • nobody really likes the idea of using a namespaced version of todo
> (@asf.todo)
> • it is possible to tweak Checkstyle and the javadoc command to enable
> the use of @todo
>
> That said:
> • todo statements generally have little to do (sic) in a javadoc comment
> anyway
> • TODO keywords are easily indexable by modern IDEs
>
> Jeremias recommends the Felix way: using //TODO comments below the
> javadoc. I’m also strongly in favour of this convention. OTOH, if I’m
> correct nobody strongly feels that @todo tags are necessary.
>
> So I think we have a consensus:
> • from now on we stop using @todo in favour of the Felix convention;
> • we will progressively remove TODO statements from javadoc comments and
> move them below in their own Java // comments
> • I remove the definition of the custom tag from build.xml
>
> Let me know if I missed anything.
>
> Thanks,
> Vincent
<snip/>
Jeremias Maerki
Re: TODO tag
Posted by Glenn Adams <gl...@skynav.com>.
Of the three options:
1. @todo
2. @asf.todo
3. //TODO
I prefer @todo, even if it means having a javadoc warning, but perhaps that
warning can be suppressed.
G.
On Thu, Sep 9, 2010 at 1:24 AM, Simon Pepping <sp...@leverkruid.eu>wrote:
> //TODO is unstructured. @todo fits into an existing syntax, viz. that
> of javadoc tags. Output in javadocs can be suppressed by '-tag
> todo:X'.
>
> My preference is therefore a javadoc tag, @todo. But I am not going to
> make a case of this.
>
> +0.
>
> Simon
>
> On Wed, Sep 08, 2010 at 12:02:29PM +0100, Vincent Hennebert wrote:
> > Ok, let me summarise this:
> >
> > ??? a @[asf.]todo tag marginally improves the formatting of a javadoc
> > comment
> > ??? nobody really likes the idea of using a namespaced version of todo
> > (@asf.todo)
> > ??? it is possible to tweak Checkstyle and the javadoc command to enable
> > the use of @todo
> >
> > That said:
> > ??? todo statements generally have little to do (sic) in a javadoc
> comment
> > anyway
> > ??? TODO keywords are easily indexable by modern IDEs
> >
> > Jeremias recommends the Felix way: using //TODO comments below the
> > javadoc. I???m also strongly in favour of this convention. OTOH, if I???m
> > correct nobody strongly feels that @todo tags are necessary.
> >
> > So I think we have a consensus:
> > ??? from now on we stop using @todo in favour of the Felix convention;
> > ??? we will progressively remove TODO statements from javadoc comments
> and
> > move them below in their own Java // comments
> > ??? I remove the definition of the custom tag from build.xml
> >
> > Let me know if I missed anything.
>
> --
> Simon Pepping
> home page: http://www.leverkruid.eu
>
Re: TODO tag
Posted by Simon Pepping <sp...@leverkruid.eu>.
//TODO is unstructured. @todo fits into an existing syntax, viz. that
of javadoc tags. Output in javadocs can be suppressed by '-tag
todo:X'.
My preference is therefore a javadoc tag, @todo. But I am not going to
make a case of this.
+0.
Simon
On Wed, Sep 08, 2010 at 12:02:29PM +0100, Vincent Hennebert wrote:
> Ok, let me summarise this:
>
> ??? a @[asf.]todo tag marginally improves the formatting of a javadoc
> comment
> ??? nobody really likes the idea of using a namespaced version of todo
> (@asf.todo)
> ??? it is possible to tweak Checkstyle and the javadoc command to enable
> the use of @todo
>
> That said:
> ??? todo statements generally have little to do (sic) in a javadoc comment
> anyway
> ??? TODO keywords are easily indexable by modern IDEs
>
> Jeremias recommends the Felix way: using //TODO comments below the
> javadoc. I???m also strongly in favour of this convention. OTOH, if I???m
> correct nobody strongly feels that @todo tags are necessary.
>
> So I think we have a consensus:
> ??? from now on we stop using @todo in favour of the Felix convention;
> ??? we will progressively remove TODO statements from javadoc comments and
> move them below in their own Java // comments
> ??? I remove the definition of the custom tag from build.xml
>
> Let me know if I missed anything.
--
Simon Pepping
home page: http://www.leverkruid.eu
Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop:
area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/
layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by Vincent Hennebert <vh...@gmail.com>.
Ok, let me summarise this:
• a @[asf.]todo tag marginally improves the formatting of a javadoc
comment
• nobody really likes the idea of using a namespaced version of todo
(@asf.todo)
• it is possible to tweak Checkstyle and the javadoc command to enable
the use of @todo
That said:
• todo statements generally have little to do (sic) in a javadoc comment
anyway
• TODO keywords are easily indexable by modern IDEs
Jeremias recommends the Felix way: using //TODO comments below the
javadoc. I’m also strongly in favour of this convention. OTOH, if I’m
correct nobody strongly feels that @todo tags are necessary.
So I think we have a consensus:
• from now on we stop using @todo in favour of the Felix convention;
• we will progressively remove TODO statements from javadoc comments and
move them below in their own Java // comments
• I remove the definition of the custom tag from build.xml
Let me know if I missed anything.
Thanks,
Vincent
On 31/08/10 12:33, Vincent Hennebert wrote:
> Hi,
>
> I just thought I would homogenize our usage of todo tags and match what
> seems to be the de facto standard (“TODO”) among current committers.
> Most @todo indeed come from very old commits. I didn’t realise that
> javadoc could do something with them, which is why that looked to me
> like a minor change that wasn’t needing prior discussion. Sorry about
> that.
>
> Ok, so there is something that can be done out of @todo tags in javadoc
> comments. Now, having to use our own namespaced version is unfortunate
> and looks overkill to me. Just to have a slightly better formatted
> javadoc? Are such comments of any use to users of the API anyway? Most
> of them rather look like pure internal development issues and should
> probably not even appear in the javadoc.
>
> Also, while @todo tags can be indexed, modern IDEs can index plain TODO
> tokens as well, so that reduces the advantage of @asf.todo IMO.
>
> If there are strong feelings against the removal of @asf.todo, I’ll
> revert the change. Otherwise, I’ll actually complete it by removing the
> definition of the custom tag in build.xml, which I hadn’t spotted.
>
> Vincent
>
>
> Simon Pepping wrote:
>> It would indeed have been better to first have a discussion and then
>> make the change. @asf.todo is specific enough that we could have
>> changed it at any time. That said, Glenn's change was also made
>> without a discussion. My javadoc does not complain about the @todo
>> tag, and I had not understood that this was a motivation.
>>
>> The javadoc documentation (of my sun-java6-jdk) is not clear about
>> this topic, and uses @todo liberally in its section about the -tag
>> option. Its most informative paragraph is this:
>>
>> "Avoiding Conflicts - If you want to slice out your own namespace, you
>> can use a dot-separated naming convention similar to that used for
>> packages: com.mycompany.todo. Sun will continue to create standard
>> tags whose names do not contain dots. Any tag you create will override
>> the behavior of a tag by the same name defined by Sun. In other words,
>> if you create a tag or taglet @todo, it will always have the same
>> behavior you define, even if Sun later creates a standard tag of the
>> same name."
>>
>> which does not even go so far as to discourage the @todo tag. It is
>> also not clear how a todo tag would be a specific asf tag, different
>> from the todo tag of any other organization. Everybody uses todo and
>> means the same with it.
>>
>> Using the widely recognized TODO keyword circumvents the tag question
>> altogether, but is outdated since the advent of tags.
>>
>> Let us discuss this and not waste effort on undoing each other's
>> expression of their point of view. Let us also not forget that working
>> in a team requires compromises; the code will never match your own
>> conventions and preferences as precisely as code in your very own
>> project. This is more so in an open project with a long history and a
>> large set of authors.
>>
>> Simon
>>
>> On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote:
>>> Vincent,
>>>
>>> Could you explain your rationale for this change? Originally, these were all
>>> marked with a non-standard '@todo' javadoc tag, which javadoc complained
>>> about, indicating that for "non-standard" tags, there should be at least one
>>> '.' present in the tag name. I had fixed this by adding the "asf." prefix,
>>> which still allowed tracking these in javadoc more easily. However, your
>>> change now removes the utility of the tag.
>>>
>>> On a more general point, wouldn't it be more useful to have a discussion
>>> about stylistic changes prior to implementing them? Just so we can get on
>>> the same page?
>>>
>>> Regards,
>>> Glenn
>>>
>>> On Fri, Aug 27, 2010 at 9:31 PM, <vh...@apache.org> wrote:
>>>
>>>> Author: vhennebert
>>>> Date: Fri Aug 27 13:31:41 2010
>>>> New Revision: 990148
>>>>
>>>> URL: http://svn.apache.org/viewvc?rev=990148&view=rev
>>>> Log:
>>>> Replaced @asf.todo with normal TODO comment
>>>>
>>>>
>>
Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop:
area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/
layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by Glenn Adams <gl...@skynav.com>.
I don't have a strong opinion on whether to keep the @asf.todo or TODO. My
main interest was removing the javadocs warnings produced (under jdk1.6
doclet) through the former use of @todo.
My point in bringing it up was to request that we discuss beforehand
prospective changes that back-out or reverse prior commits.
G.
On Tue, Aug 31, 2010 at 7:33 PM, Vincent Hennebert <vh...@gmail.com>wrote:
> Hi,
>
> I just thought I would homogenize our usage of todo tags and match what
> seems to be the de facto standard (“TODO”) among current committers.
> Most @todo indeed come from very old commits. I didn’t realise that
> javadoc could do something with them, which is why that looked to me
> like a minor change that wasn’t needing prior discussion. Sorry about
> that.
>
> Ok, so there is something that can be done out of @todo tags in javadoc
> comments. Now, having to use our own namespaced version is unfortunate
> and looks overkill to me. Just to have a slightly better formatted
> javadoc? Are such comments of any use to users of the API anyway? Most
> of them rather look like pure internal development issues and should
> probably not even appear in the javadoc.
>
> Also, while @todo tags can be indexed, modern IDEs can index plain TODO
> tokens as well, so that reduces the advantage of @asf.todo IMO.
>
> If there are strong feelings against the removal of @asf.todo, I’ll
> revert the change. Otherwise, I’ll actually complete it by removing the
> definition of the custom tag in build.xml, which I hadn’t spotted.
>
> Vincent
>
>
> Simon Pepping wrote:
> > It would indeed have been better to first have a discussion and then
> > make the change. @asf.todo is specific enough that we could have
> > changed it at any time. That said, Glenn's change was also made
> > without a discussion. My javadoc does not complain about the @todo
> > tag, and I had not understood that this was a motivation.
> >
> > The javadoc documentation (of my sun-java6-jdk) is not clear about
> > this topic, and uses @todo liberally in its section about the -tag
> > option. Its most informative paragraph is this:
> >
> > "Avoiding Conflicts - If you want to slice out your own namespace, you
> > can use a dot-separated naming convention similar to that used for
> > packages: com.mycompany.todo. Sun will continue to create standard
> > tags whose names do not contain dots. Any tag you create will override
> > the behavior of a tag by the same name defined by Sun. In other words,
> > if you create a tag or taglet @todo, it will always have the same
> > behavior you define, even if Sun later creates a standard tag of the
> > same name."
> >
> > which does not even go so far as to discourage the @todo tag. It is
> > also not clear how a todo tag would be a specific asf tag, different
> > from the todo tag of any other organization. Everybody uses todo and
> > means the same with it.
> >
> > Using the widely recognized TODO keyword circumvents the tag question
> > altogether, but is outdated since the advent of tags.
> >
> > Let us discuss this and not waste effort on undoing each other's
> > expression of their point of view. Let us also not forget that working
> > in a team requires compromises; the code will never match your own
> > conventions and preferences as precisely as code in your very own
> > project. This is more so in an open project with a long history and a
> > large set of authors.
> >
> > Simon
> >
> > On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote:
> >> Vincent,
> >>
> >> Could you explain your rationale for this change? Originally, these were
> all
> >> marked with a non-standard '@todo' javadoc tag, which javadoc complained
> >> about, indicating that for "non-standard" tags, there should be at least
> one
> >> '.' present in the tag name. I had fixed this by adding the "asf."
> prefix,
> >> which still allowed tracking these in javadoc more easily. However, your
> >> change now removes the utility of the tag.
> >>
> >> On a more general point, wouldn't it be more useful to have a discussion
> >> about stylistic changes prior to implementing them? Just so we can get
> on
> >> the same page?
> >>
> >> Regards,
> >> Glenn
> >>
> >> On Fri, Aug 27, 2010 at 9:31 PM, <vh...@apache.org> wrote:
> >>
> >>> Author: vhennebert
> >>> Date: Fri Aug 27 13:31:41 2010
> >>> New Revision: 990148
> >>>
> >>> URL: http://svn.apache.org/viewvc?rev=990148&view=rev
> >>> Log:
> >>> Replaced @asf.todo with normal TODO comment
> >>>
> >>>
> >
>
Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop:
area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/
layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by Vincent Hennebert <vh...@gmail.com>.
Hi,
I just thought I would homogenize our usage of todo tags and match what
seems to be the de facto standard (“TODO”) among current committers.
Most @todo indeed come from very old commits. I didn’t realise that
javadoc could do something with them, which is why that looked to me
like a minor change that wasn’t needing prior discussion. Sorry about
that.
Ok, so there is something that can be done out of @todo tags in javadoc
comments. Now, having to use our own namespaced version is unfortunate
and looks overkill to me. Just to have a slightly better formatted
javadoc? Are such comments of any use to users of the API anyway? Most
of them rather look like pure internal development issues and should
probably not even appear in the javadoc.
Also, while @todo tags can be indexed, modern IDEs can index plain TODO
tokens as well, so that reduces the advantage of @asf.todo IMO.
If there are strong feelings against the removal of @asf.todo, I’ll
revert the change. Otherwise, I’ll actually complete it by removing the
definition of the custom tag in build.xml, which I hadn’t spotted.
Vincent
Simon Pepping wrote:
> It would indeed have been better to first have a discussion and then
> make the change. @asf.todo is specific enough that we could have
> changed it at any time. That said, Glenn's change was also made
> without a discussion. My javadoc does not complain about the @todo
> tag, and I had not understood that this was a motivation.
>
> The javadoc documentation (of my sun-java6-jdk) is not clear about
> this topic, and uses @todo liberally in its section about the -tag
> option. Its most informative paragraph is this:
>
> "Avoiding Conflicts - If you want to slice out your own namespace, you
> can use a dot-separated naming convention similar to that used for
> packages: com.mycompany.todo. Sun will continue to create standard
> tags whose names do not contain dots. Any tag you create will override
> the behavior of a tag by the same name defined by Sun. In other words,
> if you create a tag or taglet @todo, it will always have the same
> behavior you define, even if Sun later creates a standard tag of the
> same name."
>
> which does not even go so far as to discourage the @todo tag. It is
> also not clear how a todo tag would be a specific asf tag, different
> from the todo tag of any other organization. Everybody uses todo and
> means the same with it.
>
> Using the widely recognized TODO keyword circumvents the tag question
> altogether, but is outdated since the advent of tags.
>
> Let us discuss this and not waste effort on undoing each other's
> expression of their point of view. Let us also not forget that working
> in a team requires compromises; the code will never match your own
> conventions and preferences as precisely as code in your very own
> project. This is more so in an open project with a long history and a
> large set of authors.
>
> Simon
>
> On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote:
>> Vincent,
>>
>> Could you explain your rationale for this change? Originally, these were all
>> marked with a non-standard '@todo' javadoc tag, which javadoc complained
>> about, indicating that for "non-standard" tags, there should be at least one
>> '.' present in the tag name. I had fixed this by adding the "asf." prefix,
>> which still allowed tracking these in javadoc more easily. However, your
>> change now removes the utility of the tag.
>>
>> On a more general point, wouldn't it be more useful to have a discussion
>> about stylistic changes prior to implementing them? Just so we can get on
>> the same page?
>>
>> Regards,
>> Glenn
>>
>> On Fri, Aug 27, 2010 at 9:31 PM, <vh...@apache.org> wrote:
>>
>>> Author: vhennebert
>>> Date: Fri Aug 27 13:31:41 2010
>>> New Revision: 990148
>>>
>>> URL: http://svn.apache.org/viewvc?rev=990148&view=rev
>>> Log:
>>> Replaced @asf.todo with normal TODO comment
>>>
>>>
>
Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop:
area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/
layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by Glenn Adams <gl...@skynav.com>.
by way of an amusing anecdote on this point, when I was managing the Unix
servers at the MIT AI Lab in the mid 80's I got in a bit of a contest with
RMS (richard stallman) about his liberal sharing of his login credentials
with literally *anyone* that asked; one day i found about 100 incoming FTP
sessions on his account, all coming from elsewhere, the world over; it had
dragged down the network and the vax 750 host, so I decided to take drastic
action (after having first asked him to desist, which he ignored); so i
modified the code of the FTP server to refuse more than one connection on
his account; the next day i found another 100 or so sessions, so I checked
the FTP server code: my changes were gone, with a comment left in place
"Glenn, don't bother changing this again... RMS"; at that point, i gave up,
realizing we could just continue changing it back and forth to no end;
let's avoid that same problem here;
g.
p.s. incidentally, it was that same vax 750 that the very first "internet
worm" was introduced to (by Robert Morris Jr) a few years later, in
November, 1988; i guess that was an inevitable follow on...
On Sat, Aug 28, 2010 at 5:42 PM, Glenn Adams <gl...@skynav.com> wrote:
> for what it's worth, i don't have a strong opinion on this issue (i.e.,
> whether to use @asf.todo or TODO); i explained below why i made the original
> change, and, yes, it was not discussed at the time;
>
> the point i was making below, which you echo, is that is indeed better to
> first discuss a change that undoes a set of changes than to slip it by,
> perhaps unnoticed; in the future, were i to be granted committer status, i
> certainly would not want to simply commit a change that undoes the work of
> another committer, at least without some discussion and consensus taking;
>
> g.
>
>
> On Sat, Aug 28, 2010 at 4:51 PM, Simon Pepping <sp...@leverkruid.eu>wrote:
>
>> It would indeed have been better to first have a discussion and then
>> make the change. @asf.todo is specific enough that we could have
>> changed it at any time. That said, Glenn's change was also made
>> without a discussion. My javadoc does not complain about the @todo
>> tag, and I had not understood that this was a motivation.
>>
>> The javadoc documentation (of my sun-java6-jdk) is not clear about
>> this topic, and uses @todo liberally in its section about the -tag
>> option. Its most informative paragraph is this:
>>
>> "Avoiding Conflicts - If you want to slice out your own namespace, you
>> can use a dot-separated naming convention similar to that used for
>> packages: com.mycompany.todo. Sun will continue to create standard
>> tags whose names do not contain dots. Any tag you create will override
>> the behavior of a tag by the same name defined by Sun. In other words,
>> if you create a tag or taglet @todo, it will always have the same
>> behavior you define, even if Sun later creates a standard tag of the
>> same name."
>>
>> which does not even go so far as to discourage the @todo tag. It is
>> also not clear how a todo tag would be a specific asf tag, different
>> from the todo tag of any other organization. Everybody uses todo and
>> means the same with it.
>>
>> Using the widely recognized TODO keyword circumvents the tag question
>> altogether, but is outdated since the advent of tags.
>>
>> Let us discuss this and not waste effort on undoing each other's
>> expression of their point of view. Let us also not forget that working
>> in a team requires compromises; the code will never match your own
>> conventions and preferences as precisely as code in your very own
>> project. This is more so in an open project with a long history and a
>> large set of authors.
>>
>> Simon
>>
>> On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote:
>> > Vincent,
>> >
>> > Could you explain your rationale for this change? Originally, these were
>> all
>> > marked with a non-standard '@todo' javadoc tag, which javadoc complained
>> > about, indicating that for "non-standard" tags, there should be at least
>> one
>> > '.' present in the tag name. I had fixed this by adding the "asf."
>> prefix,
>> > which still allowed tracking these in javadoc more easily. However, your
>> > change now removes the utility of the tag.
>> >
>> > On a more general point, wouldn't it be more useful to have a discussion
>> > about stylistic changes prior to implementing them? Just so we can get
>> on
>> > the same page?
>> >
>> > Regards,
>> > Glenn
>> >
>> > On Fri, Aug 27, 2010 at 9:31 PM, <vh...@apache.org> wrote:
>> >
>> > > Author: vhennebert
>> > > Date: Fri Aug 27 13:31:41 2010
>> > > New Revision: 990148
>> > >
>> > > URL: http://svn.apache.org/viewvc?rev=990148&view=rev
>> > > Log:
>> > > Replaced @asf.todo with normal TODO comment
>> > >
>> > >
>>
>> --
>> Simon Pepping
>> home page: http://www.leverkruid.eu
>>
>
>
Re: TODO tag [was: Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop:
area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/
layoutmgr/ layoutmgr/inline/ layoutmgr/table/]
Posted by Glenn Adams <gl...@skynav.com>.
for what it's worth, i don't have a strong opinion on this issue (i.e.,
whether to use @asf.todo or TODO); i explained below why i made the original
change, and, yes, it was not discussed at the time;
the point i was making below, which you echo, is that is indeed better to
first discuss a change that undoes a set of changes than to slip it by,
perhaps unnoticed; in the future, were i to be granted committer status, i
certainly would not want to simply commit a change that undoes the work of
another committer, at least without some discussion and consensus taking;
g.
On Sat, Aug 28, 2010 at 4:51 PM, Simon Pepping <sp...@leverkruid.eu>wrote:
> It would indeed have been better to first have a discussion and then
> make the change. @asf.todo is specific enough that we could have
> changed it at any time. That said, Glenn's change was also made
> without a discussion. My javadoc does not complain about the @todo
> tag, and I had not understood that this was a motivation.
>
> The javadoc documentation (of my sun-java6-jdk) is not clear about
> this topic, and uses @todo liberally in its section about the -tag
> option. Its most informative paragraph is this:
>
> "Avoiding Conflicts - If you want to slice out your own namespace, you
> can use a dot-separated naming convention similar to that used for
> packages: com.mycompany.todo. Sun will continue to create standard
> tags whose names do not contain dots. Any tag you create will override
> the behavior of a tag by the same name defined by Sun. In other words,
> if you create a tag or taglet @todo, it will always have the same
> behavior you define, even if Sun later creates a standard tag of the
> same name."
>
> which does not even go so far as to discourage the @todo tag. It is
> also not clear how a todo tag would be a specific asf tag, different
> from the todo tag of any other organization. Everybody uses todo and
> means the same with it.
>
> Using the widely recognized TODO keyword circumvents the tag question
> altogether, but is outdated since the advent of tags.
>
> Let us discuss this and not waste effort on undoing each other's
> expression of their point of view. Let us also not forget that working
> in a team requires compromises; the code will never match your own
> conventions and preferences as precisely as code in your very own
> project. This is more so in an open project with a long history and a
> large set of authors.
>
> Simon
>
> On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote:
> > Vincent,
> >
> > Could you explain your rationale for this change? Originally, these were
> all
> > marked with a non-standard '@todo' javadoc tag, which javadoc complained
> > about, indicating that for "non-standard" tags, there should be at least
> one
> > '.' present in the tag name. I had fixed this by adding the "asf."
> prefix,
> > which still allowed tracking these in javadoc more easily. However, your
> > change now removes the utility of the tag.
> >
> > On a more general point, wouldn't it be more useful to have a discussion
> > about stylistic changes prior to implementing them? Just so we can get on
> > the same page?
> >
> > Regards,
> > Glenn
> >
> > On Fri, Aug 27, 2010 at 9:31 PM, <vh...@apache.org> wrote:
> >
> > > Author: vhennebert
> > > Date: Fri Aug 27 13:31:41 2010
> > > New Revision: 990148
> > >
> > > URL: http://svn.apache.org/viewvc?rev=990148&view=rev
> > > Log:
> > > Replaced @asf.todo with normal TODO comment
> > >
> > >
>
> --
> Simon Pepping
> home page: http://www.leverkruid.eu
>
TODO tag [was: Re: svn commit: r990148 - in
/xmlgraphics/fop/trunk/src/java/org/apache/fop: area/ fo/ fo/flow/
fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/ layoutmgr/
layoutmgr/inline/ layoutmgr/table/]
Posted by Simon Pepping <sp...@leverkruid.eu>.
It would indeed have been better to first have a discussion and then
make the change. @asf.todo is specific enough that we could have
changed it at any time. That said, Glenn's change was also made
without a discussion. My javadoc does not complain about the @todo
tag, and I had not understood that this was a motivation.
The javadoc documentation (of my sun-java6-jdk) is not clear about
this topic, and uses @todo liberally in its section about the -tag
option. Its most informative paragraph is this:
"Avoiding Conflicts - If you want to slice out your own namespace, you
can use a dot-separated naming convention similar to that used for
packages: com.mycompany.todo. Sun will continue to create standard
tags whose names do not contain dots. Any tag you create will override
the behavior of a tag by the same name defined by Sun. In other words,
if you create a tag or taglet @todo, it will always have the same
behavior you define, even if Sun later creates a standard tag of the
same name."
which does not even go so far as to discourage the @todo tag. It is
also not clear how a todo tag would be a specific asf tag, different
from the todo tag of any other organization. Everybody uses todo and
means the same with it.
Using the widely recognized TODO keyword circumvents the tag question
altogether, but is outdated since the advent of tags.
Let us discuss this and not waste effort on undoing each other's
expression of their point of view. Let us also not forget that working
in a team requires compromises; the code will never match your own
conventions and preferences as precisely as code in your very own
project. This is more so in an open project with a long history and a
large set of authors.
Simon
On Sat, Aug 28, 2010 at 09:28:06AM +0800, Glenn Adams wrote:
> Vincent,
>
> Could you explain your rationale for this change? Originally, these were all
> marked with a non-standard '@todo' javadoc tag, which javadoc complained
> about, indicating that for "non-standard" tags, there should be at least one
> '.' present in the tag name. I had fixed this by adding the "asf." prefix,
> which still allowed tracking these in javadoc more easily. However, your
> change now removes the utility of the tag.
>
> On a more general point, wouldn't it be more useful to have a discussion
> about stylistic changes prior to implementing them? Just so we can get on
> the same page?
>
> Regards,
> Glenn
>
> On Fri, Aug 27, 2010 at 9:31 PM, <vh...@apache.org> wrote:
>
> > Author: vhennebert
> > Date: Fri Aug 27 13:31:41 2010
> > New Revision: 990148
> >
> > URL: http://svn.apache.org/viewvc?rev=990148&view=rev
> > Log:
> > Replaced @asf.todo with normal TODO comment
> >
> >
--
Simon Pepping
home page: http://www.leverkruid.eu
Re: svn commit: r990148 - in /xmlgraphics/fop/trunk/src/java/org/apache/fop:
area/ fo/ fo/flow/ fo/flow/table/ fo/pagination/ fo/properties/ hyphenation/
layoutmgr/ layoutmgr/inline/ layoutmgr/table/
Posted by Glenn Adams <gl...@skynav.com>.
Vincent,
Could you explain your rationale for this change? Originally, these were all
marked with a non-standard '@todo' javadoc tag, which javadoc complained
about, indicating that for "non-standard" tags, there should be at least one
'.' present in the tag name. I had fixed this by adding the "asf." prefix,
which still allowed tracking these in javadoc more easily. However, your
change now removes the utility of the tag.
On a more general point, wouldn't it be more useful to have a discussion
about stylistic changes prior to implementing them? Just so we can get on
the same page?
Regards,
Glenn
On Fri, Aug 27, 2010 at 9:31 PM, <vh...@apache.org> wrote:
> Author: vhennebert
> Date: Fri Aug 27 13:31:41 2010
> New Revision: 990148
>
> URL: http://svn.apache.org/viewvc?rev=990148&view=rev
> Log:
> Replaced @asf.todo with normal TODO comment
>
>