X-Git-Url: http://git.nikiroo.be/?p=jvcard.git;a=blobdiff_plain;f=src%2Fbe%2Fnikiroo%2Fjvcard%2FContact.java;h=4b4446de67c7ab0b9d4fed2650024a7274913421;hp=6d362f9c9aed7675fe7fb292095d021848829b52;hb=f04a32e97c847d7e2551037a4d5f6a070879215c;hpb=812124d18d08bfc270adab0cd1e289dc6126563b

diff --git a/src/be/nikiroo/jvcard/Contact.java b/src/be/nikiroo/jvcard/Contact.java
index 6d362f9..4b4446d 100644
--- a/src/be/nikiroo/jvcard/Contact.java
+++ b/src/be/nikiroo/jvcard/Contact.java
@@ -15,9 +15,13 @@ import be.nikiroo.utils.StringUtils;
 
 /**
  * A contact is the information that represent a contact person or organisation.
+ * <p>
+ * Each {@link Data} inside can be binary encoded or not: if it is binary
+ * encoded, it has an active BKey number (not -1) associated to it (of value 0
+ * if still not sorted, or unique for the whole {@link Contact} if already
+ * processed).
  * 
  * @author niki
- * 
  */
 public class Contact extends BaseClass<Data> {
 	private int nextBKey = 1;
@@ -60,7 +64,8 @@ public class Contact extends BaseClass<Data> {
 
 	/**
 	 * Return the value of the preferred data field with this name, or NULL if
-	 * none (you cannot differentiate a NULL value and no value).
+	 * none (you cannot differentiate a NULL value and no value with this method
+	 * -- for that, check {@link Contact#getPreferredData(String)}).
 	 * 
 	 * @param name
 	 *            the name to look for
@@ -77,7 +82,7 @@ public class Contact extends BaseClass<Data> {
 	 * Get the Data fields that share the given name.
 	 * 
 	 * @param name
-	 *            the name to ook for
+	 *            the name to look for
 	 * @return a list of Data fields with this name
 	 */
 	public List<Data> getData(String name) {
@@ -505,8 +510,8 @@ public class Contact extends BaseClass<Data> {
 	}
 
 	/**
-	 * Return a {@link String} representation of this contact, in vCard 2.1,
-	 * without BKeys.
+	 * Return a simple {@link String} representation of this contact without
+	 * BKeys.
 	 * 
 	 * @return the {@link String} representation
 	 */
@@ -587,12 +592,26 @@ public class Contact extends BaseClass<Data> {
 	/**
 	 * Add a {@link String} to the given {@link List}, but make sure it does not
 	 * exceed the maximum size, and truncate it if needed to fit.
+	 * <p>
+	 * Will always add one and only one {@link String} (potentially empty) at
+	 * the end of <tt>list</tt>.
 	 * 
 	 * @param list
+	 *            the list to add to
 	 * @param add
+	 *            the {@link String} to (either fully or partially) add
 	 * @param currentSize
+	 *            the current total size (managed outside of this method)
 	 * @param maxSize
-	 * @return
+	 *            the maximum size that cannot be exceeded (or -1 for
+	 *            "no maximum") -- if the maximum size would be exceeded by
+	 *            adding this {@link String}, only a part of it will be added;
+	 *            if the maximum size is already reached or exceeded (should not
+	 *            happen because of this method), an empty {@link String} will
+	 *            be added
+	 * 
+	 * @return the number of characters added (the size of the last
+	 *         {@link String} in <tt>list</tt>)
 	 */
 	static private int addToList(List<String> list, String add,
 			int currentSize, int maxSize) {