jDoc, possible leak on crash, new depth option

[jvcard.git] / src / be / nikiroo / jvcard / Contact.java

diff --git a/src/be/nikiroo/jvcard/Contact.java b/src/be/nikiroo/jvcard/Contact.java
index 9facbcd0f38cf45fe06c09f9d92f44e049c9d19d..4b4446de67c7ab0b9d4fed2650024a7274913421 100644 (file)
--- a/src/be/nikiroo/jvcard/Contact.java
+++ b/src/be/nikiroo/jvcard/Contact.java
@@ -11,13 +11,17 @@ import java.util.UUID;
 
 import be.nikiroo.jvcard.parsers.Format;
 import be.nikiroo.jvcard.parsers.Parser;
-import be.nikiroo.jvcard.resources.StringUtils;
+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;
@@ -36,28 +40,32 @@ public class Contact extends BaseClass<Data> {
        }
 
        /**
-        * Return the preferred Data field with the given name, or NULL if none.
+        * Return the preferred Data field with the given name, the first one if
+        * none is preferred, or NULL if none at all.
         * 
         * @param name
         *            the name to look for
-        * @return the Data field, or NULL
+        * 
+        * @return the {@link Data} field, or NULL
         */
        public Data getPreferredData(String name) {
-               Data first = null;
+               Data pref = null;
+               int ipref = Integer.MAX_VALUE;
                for (Data data : getData(name)) {
-                       if (first == null)
-                               first = data;
+                       if (pref == null)
+                               pref = data;
 
-                       if (data.isPreferred())
-                               return data;
+                       if (data.getPreferred() < ipref)
+                               pref = data;
                }
 
-               return first;
+               return pref;
        }
 
        /**
         * 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
@@ -74,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) {
@@ -128,7 +136,7 @@ public class Contact extends BaseClass<Data> {
         * @return the {@link String} representation
         */
        public String toString(String format, String separator) {
-               return toString(format, separator, null, -1, true, false);
+               return toString(format, separator, null, -1, true);
        }
 
        /**
@@ -170,14 +178,13 @@ public class Contact extends BaseClass<Data> {
         *            the {@link String} to use for left and right padding
         * @param width
         *            a fixed width or -1 for "as long as needed"
-        * 
         * @param unicode
-        *            allow Uniode or only ASCII characters
+        *            allow Unicode or only ASCII characters
         * 
         * @return the {@link String} representation
         */
        public String toString(String format, String separator, String padding,
-                       int width, boolean unicode, boolean removeAccents) {
+                       int width, boolean unicode) {
                StringBuilder builder = new StringBuilder();
 
                for (String str : toStringArray(format, separator, padding, width,
@@ -302,7 +309,7 @@ public class Contact extends BaseClass<Data> {
         *            a fixed width or -1 for "as long as needed"
         * @param unicode
         *            allow Uniode or only ASCII characters
-        *
+        * 
         * @return the {@link String} representation
         */
        public String[] toStringArray(String format, int width, boolean unicode) {
@@ -503,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
         */
@@ -585,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) {