You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by rm...@apache.org on 2012/08/28 01:06:38 UTC
svn commit: r1377901 - in
/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene:
document/Field.java index/IndexableField.java
Author: rmuir
Date: Mon Aug 27 23:06:38 2012
New Revision: 1377901
URL: http://svn.apache.org/viewvc?rev=1377901&view=rev
Log:
minor improvements to Field/IndexableField javadocs
Modified:
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/Field.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/IndexableField.java
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/Field.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/Field.java?rev=1377901&r1=1377900&r2=1377901&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/Field.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/Field.java Mon Aug 27 23:06:38 2012
@@ -60,7 +60,13 @@ import org.apache.lucene.index.FieldInve
*/
public class Field implements IndexableField {
+ /**
+ * Field's type
+ */
protected final FieldType type;
+ /**
+ * Field's name
+ */
protected final String name;
/** Field's value */
@@ -75,8 +81,16 @@ public class Field implements IndexableF
private transient TokenStream internalTokenStream;
private transient ReusableStringReader internalReader;
+ /**
+ * Field's boost
+ * @see #boost()
+ */
protected float boost = 1.0f;
+ /**
+ * Expert: creates a field with no initial value.
+ * Intended only for custom Field subclasses.
+ */
protected Field(String name, FieldType type) {
if (name == null) {
throw new IllegalArgumentException("name cannot be null");
@@ -279,6 +293,10 @@ public class Field implements IndexableF
fieldsData = value;
}
+ /**
+ * Expert: change the value of this field. See
+ * {@link #setStringValue(String)}.
+ */
public void setByteValue(byte value) {
if (!(fieldsData instanceof Byte)) {
throw new IllegalArgumentException("cannot change value type from " + fieldsData.getClass().getSimpleName() + " to Byte");
@@ -286,6 +304,10 @@ public class Field implements IndexableF
fieldsData = Byte.valueOf(value);
}
+ /**
+ * Expert: change the value of this field. See
+ * {@link #setStringValue(String)}.
+ */
public void setShortValue(short value) {
if (!(fieldsData instanceof Short)) {
throw new IllegalArgumentException("cannot change value type from " + fieldsData.getClass().getSimpleName() + " to Short");
@@ -293,6 +315,10 @@ public class Field implements IndexableF
fieldsData = Short.valueOf(value);
}
+ /**
+ * Expert: change the value of this field. See
+ * {@link #setStringValue(String)}.
+ */
public void setIntValue(int value) {
if (!(fieldsData instanceof Integer)) {
throw new IllegalArgumentException("cannot change value type from " + fieldsData.getClass().getSimpleName() + " to Integer");
@@ -300,6 +326,10 @@ public class Field implements IndexableF
fieldsData = Integer.valueOf(value);
}
+ /**
+ * Expert: change the value of this field. See
+ * {@link #setStringValue(String)}.
+ */
public void setLongValue(long value) {
if (!(fieldsData instanceof Long)) {
throw new IllegalArgumentException("cannot change value type from " + fieldsData.getClass().getSimpleName() + " to Long");
@@ -307,6 +337,10 @@ public class Field implements IndexableF
fieldsData = Long.valueOf(value);
}
+ /**
+ * Expert: change the value of this field. See
+ * {@link #setStringValue(String)}.
+ */
public void setFloatValue(float value) {
if (!(fieldsData instanceof Float)) {
throw new IllegalArgumentException("cannot change value type from " + fieldsData.getClass().getSimpleName() + " to Float");
@@ -314,6 +348,10 @@ public class Field implements IndexableF
fieldsData = Float.valueOf(value);
}
+ /**
+ * Expert: change the value of this field. See
+ * {@link #setStringValue(String)}.
+ */
public void setDoubleValue(double value) {
if (!(fieldsData instanceof Double)) {
throw new IllegalArgumentException("cannot change value type from " + fieldsData.getClass().getSimpleName() + " to Double");
@@ -340,23 +378,19 @@ public class Field implements IndexableF
return name;
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * The default value is <code>1.0f</code> (no boost).
+ * @see #setBoost(float)
+ */
public float boost() {
return boost;
}
- /** Sets the boost factor hits on this field. This value will be
- * multiplied into the score of all hits on this this field of this
- * document.
- *
- * <p>The boost is used to compute the norm factor for the field. By
- * default, in the {@link org.apache.lucene.search.similarities.Similarity#computeNorm(FieldInvertState, Norm)} method,
- * the boost value is multiplied by the length normalization factor and then
- * rounded by {@link org.apache.lucene.search.similarities.DefaultSimilarity#encodeNormValue(float)} before it is stored in the
- * index. One should attempt to ensure that this product does not overflow
- * the range of that encoding.
- *
- * @see org.apache.lucene.search.similarities.Similarity#computeNorm(FieldInvertState, Norm)
- * @see org.apache.lucene.search.similarities.DefaultSimilarity#encodeNormValue(float)
+ /**
+ * Sets the boost factor on this field.
+ * @see #boost()
*/
public void setBoost(float boost) {
if (boost != 1.0f) {
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/IndexableField.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/IndexableField.java?rev=1377901&r1=1377900&r2=1377901&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/IndexableField.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/IndexableField.java Mon Aug 27 23:06:38 2012
@@ -22,6 +22,8 @@ import java.io.Reader;
import org.apache.lucene.analysis.Analyzer;
import org.apache.lucene.analysis.TokenStream;
+import org.apache.lucene.search.similarities.DefaultSimilarity; // javadocs
+import org.apache.lucene.search.similarities.Similarity; // javadocs
import org.apache.lucene.util.BytesRef;
// TODO: how to handle versioning here...?
@@ -42,7 +44,26 @@ public interface IndexableField {
* of this field. */
public IndexableFieldType fieldType();
- /** Field boost (you must pre-multiply in any doc boost). */
+ /**
+ * Returns the field's index-time boost.
+ * <p>
+ * Only fields can have an index-time boost, if you want to simulate
+ * a "document boost", then you must pre-multiply it across all the
+ * relevant fields yourself.
+ * <p>The boost is used to compute the norm factor for the field. By
+ * default, in the {@link Similarity#computeNorm(FieldInvertState, Norm)} method,
+ * the boost value is multiplied by the length normalization factor and then
+ * rounded by {@link DefaultSimilarity#encodeNormValue(float)} before it is stored in the
+ * index. One should attempt to ensure that this product does not overflow
+ * the range of that encoding.
+ * <p>
+ * It is illegal to return a boost other than 1.0f for a field that is not
+ * indexed ({@link IndexableFieldType#indexed()} is false) or omits normalization values
+ * ({@link IndexableFieldType#omitNorms()} returns true).
+ *
+ * @see Similarity#computeNorm(FieldInvertState, Norm)
+ * @see DefaultSimilarity#encodeNormValue(float)
+ */
public float boost();
/** Non-null if this field has a binary value */