Clean-up javadoc, method names and open API

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/AbstractCheckerWithProblemPreferences.java

@@ -16,7 +16,10 @@ import org.eclipse.cdt.codan.core.param.IProblemPreferenceDescriptor.PreferenceT
 import org.eclipse.cdt.codan.core.param.MapProblemPreference;
 
 /**
- * AbstarctChecker that has extra method to simplify adding parameters
+ * AbstarctChecker that has extra methods to simplify adding problem
+ * preferences.
+ * Checker can produce several problems, but preferences are per problem.
+ * Shared are not supported now.
  */
 public abstract class AbstractCheckerWithProblemPreferences extends
 		AbstractChecker implements ICheckerWithPreferences {

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/AbstractProblemPreference.java

@@ -15,7 +15,8 @@ import java.io.InputStreamReader;
 import java.io.StreamTokenizer;
 
 /**
- * Default implementation for single parameter checker of type string.
+ * Default implementation of problem preference. It keeps preference metadata
+ * together with preference itself.
  * 
  */
 public abstract class AbstractProblemPreference implements IProblemPreference {
@@ -93,18 +94,6 @@ public abstract class AbstractProblemPreference implements IProblemPreference {
 		throw new UnsupportedOperationException();
 	}
 
-	public IProblemPreference getChildDescriptor(String key) {
-		throw new UnsupportedOperationException();
-	}
-
-	public IProblemPreference[] getChildDescriptors() {
-		throw new UnsupportedOperationException();
-	}
-
-	public void addChildDescriptor(IProblemPreference info) {
-		throw new UnsupportedOperationException();
-	}
-
 	@Override
 	public Object clone() {
 		try {

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/BasicProblemPreference.java

@@ -16,7 +16,9 @@ import java.io.StreamTokenizer;
 import java.util.regex.Pattern;
 
 /**
- * ParameterInfo representing a single checker parameter
+ * Preference representing a problem preference of a basic type.
+ * 
+ * @see IProblemPreferenceDescriptor.PreferenceType for types.
  * 
  */
 public class BasicProblemPreference extends AbstractProblemPreference {

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreference.java

@@ -1,18 +1,22 @@
 /*******************************************************************************
- * Copyright (c) 2009,2010 Alena Laskavaia 
+ * Copyright (c) 2009,2010 QNX Software Systems
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
- *    Alena Laskavaia  - initial API and implementation
+ *    QNX Software Systems (Alena Laskavaia)  - initial API and implementation
  *******************************************************************************/
 package org.eclipse.cdt.codan.core.param;
 
 /**
  * Value of the problem preference. If more than one it can be composite, i.e.
- * map
+ * map. Instead of implementing this interface use
+ * {@link AbstractProblemPreference} class.
+ * 
+ * @noextend This interface is not intended to be extended by clients.
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface IProblemPreference extends Cloneable, IProblemPreferenceValue,
 		IProblemPreferenceDescriptor {

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceCompositeDescriptor.java

@@ -0,0 +1,40 @@
+/*******************************************************************************
+ * Copyright (c) 2009,2010 QNX Software Systems
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *    QNX Software Systems (Alena Laskavaia)  - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.cdt.codan.core.param;
+
+/**
+ * Composite descriptor. For descriptors like map and list.
+ * 
+ * @noextend This interface is not intended to be extended by clients.
+ * @noimplement This interface is not intended to be implemented by clients.
+ */
+public interface IProblemPreferenceCompositeDescriptor {
+	/**
+	 * Available if type is composite. Returns value of subdescriptor with the
+	 * name of key. For the "list" type key is the number (index).
+	 * 
+	 * @param key
+	 *            - name of the subdescriptor.
+	 * @return
+	 */
+	IProblemPreference getChildDescriptor(String key);
+
+	/**
+	 * Available if type is list or map. Returns array of children.
+	 * 
+	 * @return
+	 */
+	IProblemPreference[] getChildDescriptors();
+
+	void addChildDescriptor(IProblemPreference info);
+
+	void removeChildDescriptor(IProblemPreference info);
+}

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceCompositeValue.java

@@ -11,9 +11,12 @@
 package org.eclipse.cdt.codan.core.param;
 
 /**
- * Interface for container type preferences
+ * Interface for container type preferences, such as map or list
+ * 
+ * @noextend This interface is not intended to be extended by clients.
+ * @noimplement This interface is not intended to be implemented by clients.
  */
-public interface IProblemPreferenceContainer {
+public interface IProblemPreferenceCompositeValue {
 	Object getChildValue(String key);
 
 	void addChildValue(String key, Object value);

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceDescriptor.java

@@ -15,14 +15,15 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Problem parameter usually key=value settings that allows to alter checker
+ * Problem parameter usually key=value settings that allow to alter checker
  * behaviour for given problem. For example if checker finds violation of naming
  * conventions for function, parameter would be the pattern of allowed names.
- * ProblemParameterInfo represent parameter meta-info for the ui. If more that
- * one parameter required ParameterInfo should describe hash or array of
- * parameters. This is only needed for auto-generated ui for parameter editing.
- * For complex case custom ui control should be used. Extend
- * AbstractProblemParamterInfo class
+ * 
+ * IProblemPreferenceDescriptor represent preference's meta-info for the ui. If
+ * more than one parameter is required it can be map or list of sub-preferences.
+ * This is only needed for auto-generated ui for parameter
+ * editing. For more complex cases custom ui control should be used. Extend
+ * {@link AbstractProblemPreference} class
  * to implement this interface.
  * 
  * @noextend This interface is not intended to be extended by clients.
@@ -113,28 +114,6 @@ public interface IProblemPreferenceDescriptor extends Cloneable {
 	 */
 	String getToolTip();
 
-	/**
-	 * Available if type is composite. Returns value of subdescriptor with the
-	 * name of key. For the "list" type key is the number (index).
-	 * 
-	 * @param key
-	 *            - name of the subdescriptor.
-	 * @return
-	 */
-	IProblemPreference getChildDescriptor(String key);
-
-	/**
-	 * Available if type is list or map. Returns array of children.
-	 * Of size 0 for basic types, keys for map, and arrays of 0 element for
-	 * array type
-	 * (since all elements are the same).
-	 * 
-	 * @return
-	 */
-	IProblemPreference[] getChildDescriptors();
-
-	void addChildDescriptor(IProblemPreference info);
-
 	Object clone();
 
 	IProblemPreference getParent();

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceValue.java

@@ -1,31 +1,53 @@
 /*******************************************************************************
- * Copyright (c) 2009,2010 Alena Laskavaia 
+ * Copyright (c) 2009,2010 QNX Software Systems
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
- *    Alena Laskavaia  - initial API and implementation
+ *    QNX Software Systems (Alena Laskavaia)  - initial API and implementation
  *******************************************************************************/
 package org.eclipse.cdt.codan.core.param;
 
 /**
  * Value of the problem preference. If more than one it can be composite, i.e.
  * map
+ * 
+ * @noextend This interface is not intended to be extended by clients.
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface IProblemPreferenceValue extends Cloneable {
 	/**
-	 * Get value of parameter if it is basic type.
+	 * Get value of preference.
 	 * 
-	 * @param key
-	 * @return
+	 * @return object that represents the value. Limited number of object types
+	 *         are allowed.
+	 * @see IProblemPreferenceDescriptor.PreferenceType
 	 */
 	Object getValue();
 
+	/**
+	 * Set value of preference represented by this object.
+	 * 
+	 * @param value
+	 */
 	void setValue(Object value);
 
+	/**
+	 * Export value in string representation required for storing in eclipse
+	 * preferences.
+	 * 
+	 * @return
+	 */
 	String exportValue();
 
+	/**
+	 * Import value from string into internal object state.
+	 * 
+	 * @param str
+	 *            - string from preferences, previously exported by exportValue
+	 *            method.
+	 */
 	void importValue(String str);
 }

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/ListProblemPreference.java

@@ -1,12 +1,12 @@
 /*******************************************************************************
- * Copyright (c) 2009 Alena Laskavaia 
+ * Copyright (c) 2009,2010 QNX Software Systems
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
- *    Alena Laskavaia  - initial API and implementation
+ *    QNX Software Systems (Alena Laskavaia)  - initial API and implementation
  *******************************************************************************/
 package org.eclipse.cdt.codan.core.param;
 
@@ -16,11 +16,12 @@ import java.util.ArrayList;
 import java.util.Iterator;
 
 /**
- * @author Alena
+ * List implementation of IProblemPreference.
  * 
+ * @noextend This class is not intended to be extended by clients.
  */
 public class ListProblemPreference extends AbstractProblemPreference implements
-		IProblemPreferenceContainer {
+		IProblemPreferenceCompositeValue, IProblemPreferenceCompositeDescriptor {
 	protected ArrayList<IProblemPreference> list = new ArrayList<IProblemPreference>(
 			1);
 
@@ -44,29 +45,28 @@ public class ListProblemPreference extends AbstractProblemPreference implements
 	}
 
 	/**
-	 * Get parameter into for element equal to key's int value,
+	 * Get parameter into for element equal to key's int value.
 	 * 
 	 * @throws NumberFormatException
 	 *             if key is not number
 	 * @throws ArrayIndexOutOfBoundsException
 	 *             is index is out of bound
 	 */
-	@Override
 	public IProblemPreference getChildDescriptor(String key)
 			throws NumberFormatException {
 		if (key == null) {
 			// special case if all element are the same return first, if key is
 			// null
-			return (IProblemPreference) getChildPreference(0).clone();
+			return (IProblemPreference) getChildDescriptor(0).clone();
 		}
 		Integer iv = Integer.valueOf(key);
 		if (iv.intValue() >= list.size()) {
 			// special case if all element are the same return first clone
-			IProblemPreference childInfo = (IProblemPreference) getChildPreference(
+			IProblemPreference childInfo = (IProblemPreference) getChildDescriptor(
 					0).clone();
 			return childInfo;
 		}
-		return getChildPreference(iv.intValue());
+		return getChildDescriptor(iv.intValue());
 	}
 
 	/**
@@ -75,7 +75,7 @@ public class ListProblemPreference extends AbstractProblemPreference implements
 	 * @param i
 	 * @param info
 	 */
-	public void setChildPreference(int i, IProblemPreference info) {
+	public void setChildDescriptor(int i, IProblemPreference info) {
 		if (info != null) {
 			while (i >= list.size()) {
 				list.add(null);
@@ -90,21 +90,19 @@ public class ListProblemPreference extends AbstractProblemPreference implements
 
 	/**
 	 * If all list elements have same info it is enough to set only first one
-	 * (index 0)
+	 * (index 0). When value is set for the other it will be replicated.
 	 */
-	@Override
 	public void addChildDescriptor(IProblemPreference info) {
 		Integer iv = Integer.valueOf(info.getKey());
 		IProblemPreference desc = (IProblemPreference) info.clone();
 		desc.setParent(this);
-		setChildPreference(iv, desc);
+		setChildDescriptor(iv, desc);
 	}
 
-	public IProblemPreference getChildPreference(int i) {
+	public IProblemPreference getChildDescriptor(int i) {
 		return list.get(i);
 	}
 
-	@Override
 	public IProblemPreference[] getChildDescriptors() {
 		return list.toArray(new IProblemPreference[list.size()]);
 	}
@@ -117,8 +115,8 @@ public class ListProblemPreference extends AbstractProblemPreference implements
 	public void addChildValue(String key, Object value) {
 		IProblemPreference pref = getChildDescriptor(key);
 		pref.setValue(value);
-		// because descriptor can be phantom  we have to set preference phisically 
-		setChildPreference(Integer.parseInt(key), pref);
+		// because descriptor can be phantom we have to set preference forcefully
+		setChildDescriptor(Integer.parseInt(key), pref);
 	}
 
 	public void removeChildValue(String key) {
@@ -174,4 +172,8 @@ public class ListProblemPreference extends AbstractProblemPreference implements
 			throw new IllegalArgumentException(str);
 		}
 	}
+
+	public void removeChildDescriptor(IProblemPreference info) {
+		list.remove(info);
+	}
 }

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/MapProblemPreference.java

@@ -1,12 +1,12 @@
 /*******************************************************************************
- * Copyright (c) 2009 Alena Laskavaia 
+ * Copyright (c) 2009,2010 QNX Software Systems
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
- *    Alena Laskavaia  - initial API and implementation
+ *    QNX Software Systems (Alena Laskavaia)  - initial API and implementation
  *******************************************************************************/
 package org.eclipse.cdt.codan.core.param;
 
@@ -15,17 +15,22 @@ import java.io.StreamTokenizer;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
 
+import org.eclipse.cdt.codan.core.model.AbstractCheckerWithProblemPreferences;
+
 /**
- * HashParamterInfo - for checker that needs more than one parameter and they
- * all different "named".
- * For example checker has 2 optional boolean parameters. For example checker
- * for parameter names
- * shadowing would have two boolean options: "check contructors" and
+ * MapProblemPreference - for checker that needs more than one preferences and
+ * they all differently "named".
+ * For example checker for parameter names shadowing would have two boolean
+ * options:
+ * "check contructors" and
  * "check setters". In this case you use this type.
+ * {@link AbstractCheckerWithProblemPreferences} class has map as default top
+ * level parameter preference.
  * 
+ * @noextend This class is not intended to be extended by clients.
  */
 public class MapProblemPreference extends AbstractProblemPreference implements
-		IProblemPreferenceContainer {
+		IProblemPreferenceCompositeValue, IProblemPreferenceCompositeDescriptor {
 	protected LinkedHashMap<String, IProblemPreference> hash = new LinkedHashMap<String, IProblemPreference>();
 
 	public MapProblemPreference() {
@@ -57,7 +62,6 @@ public class MapProblemPreference extends AbstractProblemPreference implements
 	 * Get parameter into for element by key
 	 * 
 	 */
-	@Override
 	public IProblemPreference getChildDescriptor(String key) {
 		return hash.get(key);
 	}
@@ -69,14 +73,12 @@ public class MapProblemPreference extends AbstractProblemPreference implements
 	 * @param i
 	 * @param info
 	 */
-	@Override
 	public void addChildDescriptor(IProblemPreference info) {
 		IProblemPreference desc = (IProblemPreference) info.clone();
 		desc.setParent(this);
 		hash.put(info.getKey(), desc);
 	}
 
-	@Override
 	public IProblemPreference[] getChildDescriptors() {
 		return hash.values().toArray(
 				new IProblemPreference[hash.values().size()]);
@@ -150,4 +152,8 @@ public class MapProblemPreference extends AbstractProblemPreference implements
 			throw new IllegalArgumentException(str);
 		}
 	}
+
+	public void removeChildDescriptor(IProblemPreference info) {
+		hash.remove(info);
+	}
 }