Bug 279740: Javadoc for APIs

codan/org.eclipse.cdt.codan.core/.settings/org.eclipse.jdt.core.prefs

@@ -1,4 +1,4 @@
-#Thu Mar 18 10:02:03 EDT 2010
+#Sun May 30 20:25:13 EDT 2010
 eclipse.preferences.version=1
 org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
 org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.5
@@ -7,6 +7,7 @@ org.eclipse.jdt.core.compiler.compliance=1.5
 org.eclipse.jdt.core.compiler.debug.lineNumber=generate
 org.eclipse.jdt.core.compiler.debug.localVariable=generate
 org.eclipse.jdt.core.compiler.debug.sourceFile=generate
+org.eclipse.jdt.core.compiler.doc.comment.support=enabled
 org.eclipse.jdt.core.compiler.problem.annotationSuperInterface=warning
 org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
 org.eclipse.jdt.core.compiler.problem.autoboxing=ignore
@@ -28,10 +29,22 @@ org.eclipse.jdt.core.compiler.problem.hiddenCatchBlock=warning
 org.eclipse.jdt.core.compiler.problem.incompatibleNonInheritedInterfaceMethod=warning
 org.eclipse.jdt.core.compiler.problem.incompleteEnumSwitch=warning
 org.eclipse.jdt.core.compiler.problem.indirectStaticAccess=ignore
+org.eclipse.jdt.core.compiler.problem.invalidJavadoc=warning
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTags=enabled
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsDeprecatedRef=disabled
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsNotVisibleRef=enabled
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsVisibility=public
 org.eclipse.jdt.core.compiler.problem.localVariableHiding=ignore
 org.eclipse.jdt.core.compiler.problem.methodWithConstructorName=error
 org.eclipse.jdt.core.compiler.problem.missingDeprecatedAnnotation=ignore
 org.eclipse.jdt.core.compiler.problem.missingHashCodeMethod=warning
+org.eclipse.jdt.core.compiler.problem.missingJavadocComments=warning
+org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsOverriding=disabled
+org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsVisibility=public
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription=return_tag
+org.eclipse.jdt.core.compiler.problem.missingJavadocTags=warning
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagsOverriding=disabled
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagsVisibility=public
 org.eclipse.jdt.core.compiler.problem.missingOverrideAnnotation=ignore
 org.eclipse.jdt.core.compiler.problem.missingOverrideAnnotationForInterfaceMethodImplementation=enabled
 org.eclipse.jdt.core.compiler.problem.missingSerialVersion=warning
@@ -49,13 +62,14 @@ org.eclipse.jdt.core.compiler.problem.redundantNullCheck=warning
 org.eclipse.jdt.core.compiler.problem.redundantSuperinterface=ignore
 org.eclipse.jdt.core.compiler.problem.specialParameterHidingField=disabled
 org.eclipse.jdt.core.compiler.problem.staticAccessReceiver=warning
+org.eclipse.jdt.core.compiler.problem.suppressOptionalErrors=disabled
 org.eclipse.jdt.core.compiler.problem.suppressWarnings=enabled
 org.eclipse.jdt.core.compiler.problem.syntheticAccessEmulation=ignore
 org.eclipse.jdt.core.compiler.problem.typeParameterHiding=warning
 org.eclipse.jdt.core.compiler.problem.uncheckedTypeOperation=warning
 org.eclipse.jdt.core.compiler.problem.undocumentedEmptyBlock=ignore
 org.eclipse.jdt.core.compiler.problem.unhandledWarningToken=warning
-org.eclipse.jdt.core.compiler.problem.unnecessaryElse=warning
+org.eclipse.jdt.core.compiler.problem.unnecessaryElse=ignore
 org.eclipse.jdt.core.compiler.problem.unnecessaryTypeCheck=warning
 org.eclipse.jdt.core.compiler.problem.unqualifiedFieldAccess=ignore
 org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownException=ignore
@@ -65,6 +79,7 @@ org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionWhenOverridin
 org.eclipse.jdt.core.compiler.problem.unusedImport=error
 org.eclipse.jdt.core.compiler.problem.unusedLabel=warning
 org.eclipse.jdt.core.compiler.problem.unusedLocal=warning
+org.eclipse.jdt.core.compiler.problem.unusedObjectAllocation=ignore
 org.eclipse.jdt.core.compiler.problem.unusedParameter=warning
 org.eclipse.jdt.core.compiler.problem.unusedParameterIncludeDocCommentReference=enabled
 org.eclipse.jdt.core.compiler.problem.unusedParameterWhenImplementingAbstract=disabled

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

@@ -24,6 +24,9 @@ import org.eclipse.core.resources.IResource;
 public abstract class AbstractChecker implements IChecker {
 	protected String name;
 
+	/**
+	 * Default constructor
+	 */
 	public AbstractChecker() {
 	}
 
@@ -39,15 +42,15 @@ public abstract class AbstractChecker implements IChecker {
 	 * Reports a simple problem for given file and line
 	 * 
 	 * @param id
-	 *            - problem id
+	 *        - problem id
 	 * @param file
-	 *            - file
+	 *        - file
 	 * @param lineNumber
-	 *            - line
+	 *        - line
 	 * @param args
-	 *            - problem arguments, if problem does not define error message
+	 *        - problem arguments, if problem does not define error message
-	 *            it will be error message (not recommended because of
+	 *        it will be error message (not recommended because of
-	 *            internationalization)
+	 *        internationalization)
 	 */
 	public void reportProblem(String id, IFile file, int lineNumber,
 			Object... args) {
@@ -60,9 +63,9 @@ public abstract class AbstractChecker implements IChecker {
 	 * specific file
 	 * 
 	 * @param id
-	 *            - problem id
+	 *        - problem id
 	 * @param file
-	 *            - file in scope
+	 *        - file in scope
 	 * @return problem instance
 	 */
 	public IProblem getProblemById(String id, IResource file) {
@@ -78,11 +81,11 @@ public abstract class AbstractChecker implements IChecker {
 	 * from problem definition
 	 * 
 	 * @param id
-	 *            - problem id
+	 *        - problem id
 	 * @param file
-	 *            - file
+	 *        - file
 	 * @param lineNumber
-	 *            - line
+	 *        - line
 	 */
 	public void reportProblem(String id, IFile file, int lineNumber) {
 		getProblemReporter().reportProblem(id,
@@ -109,9 +112,9 @@ public abstract class AbstractChecker implements IChecker {
 	 * Convenience method to create and return instance of IProblemLocation
 	 * 
 	 * @param file
-	 *            - file where problem is found
+	 *        - file where problem is found
 	 * @param line
-	 *            - line number 1-relative
+	 *        - line number 1-relative
 	 * @return instance of IProblemLocation
 	 */
 	protected IProblemLocation createProblemLocation(IFile file, int line) {
@@ -123,12 +126,12 @@ public abstract class AbstractChecker implements IChecker {
 	 * Convenience method to create and return instance of IProblemLocation
 	 * 
 	 * @param file
-	 *            - file where problem is found
+	 *        - file where problem is found
 	 * @param startChar
-	 *            - start char of the problem in the file, is zero-relative
+	 *        - start char of the problem in the file, is zero-relative
 	 * @param endChar
-	 *            - end char of the problem in the file, is zero-relative and
+	 *        - end char of the problem in the file, is zero-relative and
-	 *            exclusive.
+	 *        exclusive.
 	 * @return instance of IProblemLocation
 	 */
 	protected IProblemLocation createProblemLocation(IFile file, int startChar,
@@ -145,6 +148,13 @@ public abstract class AbstractChecker implements IChecker {
 		return this instanceof IRunnableInEditorChecker;
 	}
 
+	/**
+	 * report a problem
+	 * 
+	 * @param problemId - id of a problem
+	 * @param loc - problem location
+	 * @param args - extra problem arguments
+	 */
 	public void reportProblem(String problemId, IProblemLocation loc,
 			Object... args) {
 		getProblemReporter().reportProblem(problemId, loc, args);

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

@@ -13,6 +13,7 @@ package org.eclipse.cdt.codan.core.model;
 import java.util.Collection;
 import java.util.Iterator;
 
+import org.eclipse.cdt.codan.core.param.AbstractProblemPreference;
 import org.eclipse.cdt.codan.core.param.BasicProblemPreference;
 import org.eclipse.cdt.codan.core.param.FileScopeProblemPreference;
 import org.eclipse.cdt.codan.core.param.IProblemPreference;
@@ -26,7 +27,7 @@ import org.eclipse.core.runtime.IPath;
  * 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.
+ * Sharing preferences between problems is not supported now.
  */
 public abstract class AbstractCheckerWithProblemPreferences extends
 		AbstractChecker implements ICheckerWithPreferences {
@@ -39,8 +40,11 @@ public abstract class AbstractCheckerWithProblemPreferences extends
 	}
 
 	/**
-	 * @param problem
+	 * Scope preference - special preference that all file checkers should have,
-	 * @return
+	 * it allows user to include/exclude files for this specific problem.
+	 * 
+	 * @param problem - problem for which scope preference is need
+	 * @return scope problem preference, null if not defined
 	 */
 	public FileScopeProblemPreference getScopePreference(IProblem problem) {
 		FileScopeProblemPreference scope = (FileScopeProblemPreference) getTopLevelPreferenceMap(
@@ -52,9 +56,11 @@ public abstract class AbstractCheckerWithProblemPreferences extends
 	 * User can scope out some resources for this checker. Checker can use this
 	 * call to test if it should run on this resource at all or not. Test should
 	 * be done within processResource method not in enabledInContext.
+	 * This test uses user "scope" preference for the all problems that this
+	 * checker can produce.
 	 * 
-	 * @param res
+	 * @param res - resource to test on
-	 * @return
+	 * @return true if checker should report problems, fails otherwise.
 	 */
 	public boolean shouldProduceProblems(IResource res) {
 		Collection<IProblem> refProblems = getRuntime().getChechersRegistry()
@@ -70,6 +76,21 @@ public abstract class AbstractCheckerWithProblemPreferences extends
 		return false;
 	}
 
+	/**
+	 * User can scope out some resources for this checker. Checker can use this
+	 * call to test if it should run on this resource at all or produce a
+	 * specific problem on this resource. Test should
+	 * be done within processResource method not in enabledInContext, or just
+	 * before printing of a problem.
+	 * This test uses user "scope" preference for the given problem. If scope is
+	 * not defined preference it returns true.
+	 * 
+	 * @param problem - problem to test for
+	 * @param resource - resource to test on
+	 * 
+	 * @return true if problem should be report for given resource, fails
+	 *         otherwise.
+	 */
 	public boolean shouldProduceProblem(IProblem problem, IPath resource) {
 		FileScopeProblemPreference scope = getScopePreference(problem);
 		if (scope == null)
@@ -89,13 +110,13 @@ public abstract class AbstractCheckerWithProblemPreferences extends
 	 * Add a parameter
 	 * 
 	 * @param problem
-	 *            - problem that has parameter
+	 *        - problem that has parameter
 	 * @param key
-	 *            - parameter key
+	 *        - parameter key
 	 * @param label
-	 *            - parameter label - user visible
+	 *        - parameter label - user visible
 	 * @param defaultValue
-	 *            - parameter default value
+	 *        - parameter default value
 	 * @return - parameter info object
 	 */
 	public IProblemPreference addPreference(IProblemWorkingCopy problem,
@@ -109,15 +130,16 @@ public abstract class AbstractCheckerWithProblemPreferences extends
 	}
 
 	/**
-	 * Add preference of type list with default string type, list is empty by
+	 * Add preference of type list of strings, list is empty by
 	 * default
 	 * 
 	 * @param problem
-	 *            - problem
+	 *        - problem
 	 * @param key
-	 *            - preference key
+	 *        - preference key
 	 * @param label
-	 *            - preference label
+	 *        - preference label
+	 * @param itemLabel
 	 * @return preference instance of of the list, can be used to add default
 	 *         values or set different element type
 	 * 
@@ -132,18 +154,30 @@ public abstract class AbstractCheckerWithProblemPreferences extends
 		return (ListProblemPreference) map.addChildDescriptor(list);
 	}
 
+	/**
+	 * Add preference for the given problem with default value
+	 * 
+	 * @param problem
+	 * @param pref - preference
+	 * @param defaultValue - default value of the preference
+	 * @return added preference
+	 */
 	public IProblemPreference addPreference(IProblemWorkingCopy problem,
-			IProblemPreference info, Object defaultValue) {
+			IProblemPreference pref, Object defaultValue) {
 		MapProblemPreference map = getTopLevelPreferenceMap(problem);
-		map.addChildDescriptor(info);
+		String key = pref.getKey();
-		setDefaultPreferenceValue(problem, info.getKey(), defaultValue);
+		pref = map.addChildDescriptor(pref);
-		return info;
+		setDefaultPreferenceValue(problem, key, defaultValue);
+		return pref;
 	}
 
 	/**
-	 * @param problem
+	 * Convenience method for setting default preference value for checker that
-	 * @param key
+	 * uses "map" as top level problem preference.
-	 * @param defaultValue
+	 * 
+	 * @param problem - problem for which to set default value for a prefence
+	 * @param key - preference key
+	 * @param defaultValue - value of preference to be set
 	 */
 	protected void setDefaultPreferenceValue(IProblemWorkingCopy problem,
 			String key, Object defaultValue) {
@@ -153,14 +187,20 @@ public abstract class AbstractCheckerWithProblemPreferences extends
 	}
 
 	/**
+	 * Return "map" problem preference for a give problem, if problem
+	 * has preference different than a map, it will throw ClassCastException.
+	 * If top level preference does not exist create a map preference with name
+	 * "params"
+	 * and return it.
+	 * 
 	 * @param problem
-	 * @return
+	 * @return top level preference if it is a map
 	 */
 	protected MapProblemPreference getTopLevelPreferenceMap(IProblem problem) {
 		MapProblemPreference map = (MapProblemPreference) problem
 				.getPreference();
 		if (map == null) {
-			map = new MapProblemPreference("params", ""); //$NON-NLS-1$ //$NON-NLS-2$
+			map = new MapProblemPreference(AbstractProblemPreference.PARAM, ""); //$NON-NLS-1$
 			if (problem instanceof IProblemWorkingCopy) {
 				((IProblemWorkingCopy) problem).setPreference(map);
 			}
@@ -169,11 +209,12 @@ public abstract class AbstractCheckerWithProblemPreferences extends
 	}
 
 	/**
-	 * Return value for the key in the top level preference map
+	 * Returns value of the preference for the key in the top level
+	 * preference map for the given problem
 	 * 
-	 * @param problem
+	 * @param problem - problem for which to get the preference
-	 * @param key
+	 * @param key - preference key
-	 * @return
+	 * @return value of the preference
 	 */
 	public Object getPreference(IProblem problem, String key) {
 		return ((MapProblemPreference) problem.getPreference())

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

@@ -52,6 +52,11 @@ public abstract class AbstractProblemLocation implements IProblemLocation {
 		return extra;
 	}
 
+	/**
+	 * Sets extra data for the problem location
+	 * 
+	 * @param data
+	 */
 	public void setData(Object data) {
 		this.extra = data;
 	}
@@ -65,19 +70,15 @@ public abstract class AbstractProblemLocation implements IProblemLocation {
 		return file;
 	}
 
-	/*
+	/**
-	 * (non-Javadoc)
+	 * Problem line number referenced in problem view in location field
-	 * 
-	 * @see org.eclipse.cdt.codan.core.model.IProblemLocation#getLine()
 	 */
 	public int getLineNumber() {
 		return getStartingLineNumber();
 	}
 
-	/*
+	/**
-	 * (non-Javadoc)
+	 * @return line number where problem starts
-	 * 
-	 * @see org.eclipse.cdt.codan.core.model.IProblemLocation#getStartLine()
 	 */
 	public int getStartingLineNumber() {
 		return line;

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

@@ -14,7 +14,8 @@ import org.eclipse.core.resources.IMarker;
 
 /**
  * 
- * Represents Severity of the codan problem. It is directly mapped to markers severity,
+ * Represents Severity of the codan problem. It is directly mapped to markers
+ * severity,
  * therefore not intended to be extended.
  * 
  * @noextend This class is not intended to be extended by clients.
@@ -22,13 +23,27 @@ import org.eclipse.core.resources.IMarker;
  * 
  */
 public enum CodanSeverity {
-	Info(IMarker.SEVERITY_INFO), Warning(IMarker.SEVERITY_WARNING), Error(IMarker.SEVERITY_ERROR);
+	/**
+	 * Info severity
+	 */
+	Info(IMarker.SEVERITY_INFO),
+	/**
+	 * Warning severity
+	 */
+	Warning(IMarker.SEVERITY_WARNING),
+	/**
+	 * Error severity
+	 */
+	Error(IMarker.SEVERITY_ERROR);
 	private int value;
 
 	private CodanSeverity(int value) {
 		this.value = value;
 	}
 
+	/**
+	 * @return int value of the severity
+	 */
 	public int intValue() {
 		return value;
 	}

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

@@ -13,10 +13,8 @@ package org.eclipse.cdt.codan.core.model;
 import org.eclipse.core.resources.IResource;
 
 /**
- * Interface that checker must implement. CDT Checker must be able to process a
+ * Interface that checker must implement (through extending directly or
- * resource.
+ * indirectly {@link AbstractChecker}.
- * 
- * Clients may implement and extend this interface.
  * 
  * <p>
  * <strong>EXPERIMENTAL</strong>. This class or interface has been added as part
@@ -26,33 +24,36 @@ import org.eclipse.core.resources.IResource;
  * 
  * @noextend This interface is not intended to be extended by clients.
  * @noimplement This interface is not intended to be implemented by clients.
- *              Extend AbstractChecker class instead.
+ *              Extend {@link AbstractChecker} class instead.
  */
 public interface IChecker {
 	/**
 	 * Main method that checker should implement that actually detects errors
 	 * 
 	 * @param resource
-	 *            - resource to run on
+	 *        - resource to run on
-	 * @return true if need to traverse children
+	 * @return true if framework should traverse children of the resource and
+	 *         run this checkers on them again
 	 */
 	boolean processResource(IResource resource);
 
 	/**
 	 * Implement this method to trim down type of resource you are interested
-	 * in, usually it will be c/c++ files only
+	 * in, usually it will be c/c++ files only. This method should be
+	 * independent from current user preferences.
 	 * 
 	 * @param resource
-	 *            - resource to run on
+	 *        - resource to run on
-	 * @return
+	 * @return - true if checker should be run on this resource
 	 */
 	boolean enabledInContext(IResource resource);
 
 	/**
 	 * Checker must implement this method to determine if it can run in editor
-	 * "as you type", checker must be really light weight to run in this mode.
+	 * "as you type". Checker must be really light weight to run in this mode.
-	 * Checker must also must implement IRunnableInEditorChecker if it returns
+	 * If it returns true, checker must also implement
-	 * true. Checker can return false if check is non-trivial and takes a long
+	 * {@link IRunnableInEditorChecker}.
+	 * Checker should return false if check is non-trivial and takes a long
 	 * time.
 	 * 
 	 * @return true if need to be run in editor as user types, and false

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

@@ -13,8 +13,9 @@ package org.eclipse.cdt.codan.core.model;
 /**
  * Interface for checker with parameters, if checker implements this interface
  * method would be called on initialization so checker has a chance to set
- * default values for its parameters
+ * default values for its parameters. It is recommended to use
- * <p>
+ * {@link AbstractCheckerWithProblemPreferences} insted of implementing it
+ * directly.<p>
  * <strong>EXPERIMENTAL</strong>. This class or interface has been added as part
  * of a work in progress. There is no guarantee that this API will work or that
  * it will remain the same.
@@ -28,7 +29,7 @@ public interface ICheckerWithPreferences {
 	 * parameters.
 	 * 
 	 * @param problem
-	 *            - instance of problem working copy
+	 *        - instance of problem working copy
 	 */
 	void initPreferences(IProblemWorkingCopy problem);
 }

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

@@ -27,36 +27,37 @@ public interface ICheckersRegistry extends Iterable<IChecker> {
 	/**
 	 * Iterator for registered checkers
 	 * 
-	 * @return
+	 * @return iterator for registered checkers
 	 */
-	public abstract Iterator<IChecker> iterator();
+	public Iterator<IChecker> iterator();
 
 	/**
-	 * Add another checker
+	 * Add a checker
 	 * 
-	 * @param checker
+	 * @param checker instance
 	 */
-	public abstract void addChecker(IChecker checker);
+	public void addChecker(IChecker checker);
 
 	/**
-	 * Add problem p with default category by category id into default profile,
+	 * Add problem p into a category defined by a category id into default
-	 * category must exists in default profile
+	 * profile, category must exists in default profile
 	 * 
 	 * @param p
-	 *            - problem
+	 *        - problem
 	 * @param categoryId
-	 *            - category id
+	 *        - category id
 	 */
-	public abstract void addProblem(IProblem p, String categoryId);
+	public void addProblem(IProblem p, String categoryId);
 
 	/**
-	 * Add subcategory with id categoryId into parent category, if parent does
+	 * Add subcategory category into parent category with the id of
-	 * not exist in default, profile - if not will be added to the root
+	 * parentCategoryId, if parent does not exist in the default profile or it
+	 * is a null - it will be added to the root
 	 * 
 	 * @param category
-	 *            - new category
+	 *        - new category
 	 * @param parentCategoryId
-	 *            - parent category id
+	 *        - parent category id
 	 */
 	public abstract void addCategory(IProblemCategory category,
 			String parentCategoryId);
@@ -67,9 +68,9 @@ public interface ICheckersRegistry extends Iterable<IChecker> {
 	 * enabled.
 	 * 
 	 * @param c
-	 *            - checker
+	 *        - checker
 	 * @param p
-	 *            - problem
+	 *        - problem
 	 */
 	public void addRefProblem(IChecker c, IProblem p);
 
@@ -77,55 +78,57 @@ public interface ICheckersRegistry extends Iterable<IChecker> {
 	 * Return collection of problem that this checker can produce
 	 * 
 	 * @param checker
-	 * @return
+	 * @return collection of problems
 	 */
 	public Collection<IProblem> getRefProblems(IChecker checker);
 
 	/**
-	 * Get default profile, default profile is kind of "Installation Default".
+	 * Default profile is kind of "Installation Default".
-	 * Always the same, comes from default in checker extensions
+	 * Always the same, comes from defaults in checker extensions or APIs added
 	 * 
-	 * @return
+	 * @return default profile
 	 */
-	public abstract IProblemProfile getDefaultProfile();
+	public IProblemProfile getDefaultProfile();
 
 	/**
 	 * Get workspace profile. User can change setting for workspace profile.
 	 * 
-	 * @return profile
+	 * @return workspace profile
 	 */
-	public abstract IProblemProfile getWorkspaceProfile();
+	public IProblemProfile getWorkspaceProfile();
 
 	/**
-	 * Get resource profile. For example given directory can have different
+	 * Get resource profile. For example given project can have different
-	 * profile than parent project.
+	 * profile than a workspace.
 	 * 
 	 * @param element
-	 *            - resource
+	 *        - resource
-	 * @return profile
+	 * @return resource profile
 	 */
-	public abstract IProblemProfile getResourceProfile(IResource element);
+	public IProblemProfile getResourceProfile(IResource element);
 
 	/**
 	 * Returns profile working copy for given resource element. (If profile is
 	 * not specified for given element it will search for parent resource and so
-	 * on).
+	 * on). If you planning on editing it this method should be used instead of
+	 * getResourceProfile. You have to save your changes after updating a
+	 * working copy, using {@link #updateProfile(IResource, IProblemProfile)}
+	 * method.
 	 * 
+	 * @noreference This method is not intended to be referenced by clients.
 	 * @param element
-	 * @return
+	 * @return resource profile
 	 */
-	public abstract IProblemProfile getResourceProfileWorkingCopy(
+	public IProblemProfile getResourceProfileWorkingCopy(IResource element);
-			IResource element);
 
 	/**
 	 * Set profile for resource.
 	 * 
 	 * @noreference This method is not intended to be referenced by clients.
 	 * @param resource
-	 *            - resource
+	 *        - resource
 	 * @param profile
-	 *            - problems profile
+	 *        - problems profile
 	 */
-	public abstract void updateProfile(IResource resource,
+	public void updateProfile(IResource resource, IProblemProfile profile);
-			IProblemProfile profile);
 }

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

@@ -14,10 +14,10 @@ import org.eclipse.core.resources.IResource;
 import org.eclipse.core.runtime.IProgressMonitor;
 
 /**
- * Interface for "Codan Builder". Clients can cann processResource method to
+ * Interface for "Codan Builder". Clients can call processResource method to
- * traverse the resource tree, calling all the checker (this interface allows
+ * traverse the resource tree. It will be calling all the checkers (this
- * to call framework without using UI). You can obtain instance of this
+ * interface allows to call framework without using UI). You can obtain instance
- * class as CodanRuntime.getInstance().getBuilder()
+ * of this class as CodanRuntime.getInstance().getBuilder()
  * 
  * @noextend This interface is not intended to be extended by clients.
  * @noimplement This interface is not intended to be implemented by clients.
@@ -25,6 +25,7 @@ import org.eclipse.core.runtime.IProgressMonitor;
 public interface ICodanBuilder {
 	/**
 	 * Run code analysis on given resource
+	 * 
 	 * @param resource - resource to process
 	 * @param monitor - progress monitor
 	 */

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

@@ -17,10 +17,10 @@ import org.eclipse.cdt.codan.core.param.IProblemPreference;
  * "Null Pointer Dereference" is a problem. It has user visible Name and Message
  * (translatable), as well as some other parameters, changeable by user such as
  * enablement, severity and so on. Same problem cannot have two severities
- * determined by runtime. If it is the case - two Problem should be created
+ * determined by runtime. If it is the case - two Problems should be created
- * (i.e. one for error and one for warning).
+ * (i.e. one for error and one for warning). All of problem attributes are
+ * defined in a checker extension point.
  * 
- * Clients may implement and extend this interface.
  * <p>
  * <strong>EXPERIMENTAL</strong>. This class or interface has been added as part
  * of a work in progress. There is no guarantee that this API will work or that
@@ -33,6 +33,8 @@ import org.eclipse.cdt.codan.core.param.IProblemPreference;
 public interface IProblem extends IProblemElement {
 	/**
 	 * Name of the problem - user visible "title", not the message
+	 * 
+	 * @return title of the problem
 	 */
 	String getName();
 
@@ -40,7 +42,7 @@ public interface IProblem extends IProblemElement {
 	 * Unique problem id. Should be qualified by plugin name to maintain
 	 * uniqueness.
 	 * 
-	 * @return
+	 * @return unique problem id
 	 */
 	String getId();
 
@@ -66,25 +68,24 @@ public interface IProblem extends IProblemElement {
 	String getMessagePattern();
 
 	/**
-	 * Get root preference descriptor - contains description of types of all the
+	 * Get root preference descriptor or null if not defined (used by ui to
-	 * parameters or null if not defined (used by ui to generate user controls
+	 * generate user controls for changing parameters)
-	 * for changing parameters)
 	 * 
-	 * @return
+	 * @return root preference or null
 	 */
 	public IProblemPreference getPreference();
 
 	/**
 	 * Get short description of a problem
 	 * 
-	 * @return
+	 * @return description
 	 */
 	public String getDescription();
 
 	/**
 	 * Return marker id for the problem
 	 * 
-	 * @return
+	 * @return marker id
 	 */
 	public String getMarkerType();
 }

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

@@ -11,30 +11,35 @@
 package org.eclipse.cdt.codan.core.model;
 
 /**
- * Problem category.
+ * Problem category. Allows to group problems.
  * <p>
-* <strong>EXPERIMENTAL</strong>. This class or interface has been added as
+ * <strong>EXPERIMENTAL</strong>. This class or interface has been added as part
-* part of a work in progress. There is no guarantee that this API will
+ * of a work in progress. There is no guarantee that this API will work or that
-* work or that it will remain the same.
+ * it will remain the same.
-* </p>
+ * </p>
- * Clients may extend and implement this interface.
+ * 
+ * @noextend This interface is not intended to be extended by clients.
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface IProblemCategory extends IProblemElement {
 	/**
 	 * Category name
+	 * 
+	 * @return category name
 	 */
 	String getName();
 
 	/**
 	 * Unique category id
+	 * 
 	 * @return id
 	 */
 	String getId();
 
 	/**
 	 * Category children (other categories or problems)
-	 * @return
+	 * 
+	 * @return children of the category
 	 */
 	IProblemElement[] getChildren();
-
 }

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

@@ -27,9 +27,9 @@ public interface IProblemLocationFactory {
 	 * Create and return instance of IProblemLocation
 	 * 
 	 * @param file
-	 *            - file where problem is found
+	 *        - file where problem is found
 	 * @param line
-	 *            - line number where problem is found, starts with 1
+	 *        - line number where problem is found, starts with 1
 	 * @return instance of IProblemLocation
 	 */
 	public IProblemLocation createProblemLocation(IFile file, int line);
@@ -38,12 +38,12 @@ public interface IProblemLocationFactory {
 	 * Create and return instance of IProblemLocation
 	 * 
 	 * @param file
-	 *            - file where problem is found
+	 *        - file where problem is found
 	 * @param startChar
-	 *            - start char of the problem in the file, is zero-relative
+	 *        - start char of the problem in the file, is zero-relative
 	 * @param endChar
-	 *            - end char of the problem in the file, is zero-relative and
+	 *        - end char of the problem in the file, is zero-relative and
-	 *            exclusive.
+	 *        exclusive.
 	 * @return instance of IProblemLocation
 	 */
 	public IProblemLocation createProblemLocation(IFile file, int startChar,
@@ -52,17 +52,16 @@ public interface IProblemLocationFactory {
 	/**
 	 * Create and return instance of IProblemLocation
 	 * 
-	 * @param file
+	 * @param astFile - file where problem is found
-	 *            - file where problem is found
+	 * @param startChar - start char of the problem in the file, is
-	 * @param startChar
+	 *        zero-relative
-	 *            - start char of the problem in the file, is zero-relative
+	 * @param endChar - end char of the problem in the file, is zero-relative and
-	 * @param endChar
+	 *        exclusive.
-	 *            - end char of the problem in the file, is zero-relative and
+	 * 
-	 *            exclusive.
 	 * @param line
-	 *            - start line number (for visualisation purposes)
+	 *        - start line number (for visualisation purposes)
 	 * @return instance of IProblemLocation
 	 */
 	public IProblemLocation createProblemLocation(IFile astFile,
-			int nodeOffset, int i, int line);
+			int startChar, int endChar, int line);
 }

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

@@ -10,19 +10,26 @@
  *******************************************************************************/
 package org.eclipse.cdt.codan.core.model;
 
+import org.eclipse.cdt.codan.internal.core.CheckersRegistry;
+
 /**
  * Problem Profile contains tree of categories and problems. For the user
  * the profile is quick way to switch between problem sets depending on the
  * task he is doing (i.e. find real bugs, vs doing code style report)
  * User can set different profiles for different projects.
  * Profiles can have different categories and different problem sets,
- * problems with the same id can have different severities/enablement in different profiles.
+ * problems with the same id can have different severities/enablement in
- * Category tree can have few reference to a same problem, but only instance of Problem
+ * different profiles.
- * with the same id can exist in the same profile (i.e. two category can have same problem listed in both, 
+ * Category tree can have few reference to a same problem, but only instance of
+ * Problem
+ * with the same id can exist in the same profile (i.e. two category can have
+ * same problem listed in both,
  * but they both should point to the same problem instance).
  * 
- * To obtain read-only profile use method {@link CheckersRegistry#getResourceProfile,
+ * To obtain read-only profile use method
- * CheckersRegistry#getDefaultProfile() or CheckersRegistry#getWorkspaceProfile()}
+ * {@link CheckersRegistry#getResourceProfile},
+ * {@link CheckersRegistry#getDefaultProfile()} or
+ * {@link CheckersRegistry#getWorkspaceProfile()}
  * 
  * @noextend This interface is not intended to be extended by clients.
  * @noimplement This interface is not intended to be implemented by clients.
@@ -37,7 +44,7 @@ public interface IProblemProfile extends IProblemElement {
 	 * Find and return problem by id if it contained in this profile
 	 * 
 	 * @param id
-	 *            - problem id
+	 *        - problem id
 	 * @return problem instance
 	 */
 	IProblem findProblem(String id);
@@ -46,13 +53,14 @@ public interface IProblemProfile extends IProblemElement {
 	 * Find and return category by id if it is contained in this profile
 	 * 
 	 * @param id
-	 *            - category id
+	 *        - category id
 	 * @return category instance
 	 */
 	IProblemCategory findCategory(String id);
 
 	/**
-	 * Get all problems defined in this profile (if problem duplicated in a category tree, it returns only one instance of each)
+	 * Get all problems defined in this profile (if problem duplicated in a
+	 * category tree, it returns only one instance of each)
 	 * 
 	 * @return array of problems defined in profile
 	 */

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

@@ -13,7 +13,6 @@ package org.eclipse.cdt.codan.core.model;
 /**
  * IProblemReporter - interface to report problems
  * 
- * Clients may implement and extend this interface
  * <p>
  * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
  * part of a work in progress. There is no guarantee that this API will
@@ -21,14 +20,22 @@ package org.eclipse.cdt.codan.core.model;
  * </p>
  */
 public interface IProblemReporter {
+	/**
+	 * id of generic codan problem marker
+	 */
 	public static final String GENERIC_CODE_ANALYSIS_MARKER_TYPE = "org.eclipse.cdt.codan.core.codanProblem"; //$NON-NLS-1$
 
 	/**
 	 * Report a problem with "problemId" id on the location determined by "loc",
 	 * using problem specific error message customized by args.
+	 * 
 	 * @param problemId - id of the problem registered with a checker
-	 * @param loc - location object
+	 * @param loc - location object, can be created using
-	 * @param args - custom arguments, can be null, in this case default message is reported
+	 *        getRuntime().getProblemLocationFactory().createProblemLocation
+	 *        methods
+	 * @param args - custom arguments, can be null, in this case default message
+	 *        is reported
 	 */
-	public void reportProblem(String problemId, IProblemLocation loc, Object... args);
+	public void reportProblem(String problemId, IProblemLocation loc,
+			Object... args);
 }

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

@@ -28,7 +28,7 @@ public interface IProblemWorkingCopy extends IProblem {
 	 * in profile not by checker when printing problems.
 	 * 
 	 * @param sev
-	 *            - codan severity
+	 *        - codan severity
 	 */
 	void setSeverity(CodanSeverity sev);
 
@@ -36,7 +36,7 @@ public interface IProblemWorkingCopy extends IProblem {
 	 * Set checker enablement.
 	 * 
 	 * @param enabled
-	 *            - true if problem is enabled in profile
+	 *        - true if problem is enabled in profile
 	 */
 	void setEnabled(boolean enabled);
 
@@ -46,7 +46,7 @@ public interface IProblemWorkingCopy extends IProblem {
 	 * pattern should be set in checker extension
 	 * 
 	 * @param messagePattern
-	 *            - java style message patter i.e. "Variable {0} is never used"
+	 *        - java style message patter i.e. "Variable {0} is never used"
 	 */
 	void setMessagePattern(String messagePattern);
 
@@ -55,6 +55,8 @@ public interface IProblemWorkingCopy extends IProblem {
 	 * initialization only, which would the default. User control this values
 	 * through ui later.
 	 * 
+	 * @param pref - preference to set
+	 * 
 	 */
 	public void setPreference(IProblemPreference pref);
 
@@ -62,7 +64,7 @@ public interface IProblemWorkingCopy extends IProblem {
 	 * Set problem description
 	 * 
 	 * @param desc
-	 *            - problem description - short version, but longer than name
+	 *        - problem description - short version, but longer than name
 	 */
 	public void setDescription(String desc);
 }

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IBasicBlock.java

@@ -1,21 +1,33 @@
 package org.eclipse.cdt.codan.core.model.cfg;
 
-
 /**
- * 
+ * Control flow graph basic block node - super interface of all nodes.
- * Control flow graph basic block node - superinterface of all nodes. Each node
+ * It has set on incoming nodes and outgoing nodes.
- * has iterator and size over incoming and outgoing arc
  * <p/>
- * The following are speciazed versions of the nodes:
- * <li>{@link IStartNode} - start node of the graph
- * <li>{@link I}
  */
 public interface IBasicBlock {
+	/**
+	 * Incoming nodes - nodes that executed immediately before this one
+	 * 
+	 * @return array of incoming nodes, empty array of none
+	 */
 	IBasicBlock[] getIncomingNodes();
 
+	/**
+	 * Outgoing nodes - where control would be passed. Can be more than one if
+	 * node is condition.
+	 * 
+	 * @return array of outgoing nodes, empty of none
+	 */
 	IBasicBlock[] getOutgoingNodes();
 
+	/**
+	 * @return size of array of incoming nodes
+	 */
 	int getIncomingSize();
 
+	/**
+	 * @return size of array of outgoing nodes
+	 */
 	int getOutgoingSize();
 }

codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IDecisionNode.java

@@ -10,7 +10,7 @@ public interface IDecisionNode extends IBasicBlock, ISingleIncoming {
 	/**
 	 * Node where branches of decision node merge
 	 * 
-	 * @return
+	 * @return the "merge" node
 	 */
 	IConnectorNode getMergeNode();
 }

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

@@ -21,7 +21,10 @@ import java.io.StreamTokenizer;
  * 
  */
 public abstract class AbstractProblemPreference implements IProblemPreference {
-	public static final String PARAM = "param"; //$NON-NLS-1$
+	/**
+	 * default key for a preference
+	 */
+	public static final String PARAM = "params"; //$NON-NLS-1$
 	private String key = PARAM;
 	private String label = ""; //$NON-NLS-1$
 	private String toolTip = null;
@@ -44,6 +47,11 @@ public abstract class AbstractProblemPreference implements IProblemPreference {
 		return uiInfo;
 	}
 
+	/**
+	 * Set preference key for itself
+	 * 
+	 * @param key
+	 */
 	public void setKey(String key) {
 		if (key == null)
 			throw new NullPointerException("key"); //$NON-NLS-1$
@@ -68,16 +76,31 @@ public abstract class AbstractProblemPreference implements IProblemPreference {
 		return true;
 	}
 
+	/**
+	 * Sets a label for UI control
+	 * 
+	 * @param label
+	 */
 	public void setLabel(String label) {
 		if (label == null)
 			throw new NullPointerException("Label cannot be null"); //$NON-NLS-1$
 		this.label = label;
 	}
 
+	/**
+	 * Sets tooltip for ui control. Not supported now.
+	 * 
+	 * @param tooltip
+	 */
 	public void setToolTip(String tooltip) {
 		this.toolTip = tooltip;
 	}
 
+	/**
+	 * Sets uiinfo for ui control. Not supported now.
+	 * 
+	 * @param uiinfo
+	 */
 	public void setUiInfo(String uiinfo) {
 		this.uiInfo = uiinfo;
 	}
@@ -141,7 +164,6 @@ public abstract class AbstractProblemPreference implements IProblemPreference {
 
 	/**
 	 * @param tokenizer
-	 * @return
 	 * @throws IOException
 	 */
 	public abstract void importValue(StreamTokenizer tokenizer)

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

@@ -29,6 +29,11 @@ public class BasicProblemPreference extends AbstractProblemPreference {
 		return type;
 	}
 
+	/**
+	 * Set preferene type
+	 * 
+	 * @param type
+	 */
 	public void setType(PreferenceType type) {
 		if (type == null)
 			throw new NullPointerException("Type cannot be null"); //$NON-NLS-1$
@@ -44,7 +49,6 @@ public class BasicProblemPreference extends AbstractProblemPreference {
 	 *        - label to be shown to user
 	 * @param type
 	 *        - parameter type
-	 * @return
 	 */
 	public BasicProblemPreference(String key, String label, PreferenceType type) {
 		this(key, label);
@@ -58,7 +62,6 @@ public class BasicProblemPreference extends AbstractProblemPreference {
 	 *        - property id (use in actual property hash of a checker)
 	 * @param label
 	 *        - label to be shown to user
-	 * @return
 	 */
 	public BasicProblemPreference(String key, String label) {
 		setKey(key);

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

@@ -66,6 +66,7 @@ public class FileScopeProblemPreference extends AbstractProblemPreference {
 	 * Set attribute to a value. Possible keys are EXCUSION and INCLUSION
 	 * 
 	 * @param key
+	 * @param value
 	 */
 	public void setAttribute(String key, IPath[] value) {
 		if (key == EXCLUSION)

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

@@ -22,19 +22,30 @@ public interface IProblemPreferenceCompositeDescriptor {
 	 * name of key. For the "list" type key is the number (index).
 	 * 
 	 * @param key
-	 *            - name of the subdescriptor.
+	 *        - name of the subdescriptor.
-	 * @return
+	 * @return child preference of the given key
 	 */
 	IProblemPreference getChildDescriptor(String key);
 
 	/**
 	 * Available for composite types. Returns array of children.
 	 * 
-	 * @return
+	 * @return array of children. 0 size of none.
 	 */
 	IProblemPreference[] getChildDescriptors();
 
-	IProblemPreference addChildDescriptor(IProblemPreference info);
+	/**
+	 * Add preference
+	 * 
+	 * @param preference
+	 * @return added preference
+	 */
+	IProblemPreference addChildDescriptor(IProblemPreference preference);
 
-	void removeChildDescriptor(IProblemPreference info);
+	/**
+	 * Remove preference
+	 * 
+	 * @param preference
+	 */
+	void removeChildDescriptor(IProblemPreference preference);
 }