Improve javadoc for scanner and parser extension API

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/parser/AbstractScannerExtensionConfiguration.java

@@ -30,54 +30,54 @@ import org.eclipse.cdt.internal.core.parser.scanner2.ObjectStyleMacro;
 public abstract class AbstractScannerExtensionConfiguration implements IScannerExtensionConfiguration {
 
 	/*
-	 * @see org.eclipse.cdt.internal.core.parser.scanner2.IScannerExtensionConfiguration#getAdditionalKeywords()
+	 * @see org.eclipse.cdt.core.dom.parser.IScannerExtensionConfiguration#initializeMacroValuesTo1()
-	 */
-	public CharArrayIntMap getAdditionalKeywords() {
-		return null;
-	}
-
-	/*
-	 * @see org.eclipse.cdt.internal.core.parser.scanner2.IScannerExtensionConfiguration#getAdditionalMacros()
-	 */
-	public CharArrayObjectMap getAdditionalMacros() {
-		return null;
-	}
-
-	/*
-	 * @see org.eclipse.cdt.internal.core.parser.scanner2.IScannerExtensionConfiguration#getAdditionalPreprocessorKeywords()
-	 */
-	public CharArrayIntMap getAdditionalPreprocessorKeywords() {
-		return null;
-	}
-
-	/*
-	 * @see org.eclipse.cdt.internal.core.parser.scanner2.IScannerExtensionConfiguration#initializeMacroValuesTo1()
 	 */
 	public boolean initializeMacroValuesTo1() {
 		return false;
 	}
 
 	/*
-	 * @see org.eclipse.cdt.internal.core.parser.scanner2.IScannerExtensionConfiguration#support$InIdentifiers()
+	 * @see org.eclipse.cdt.core.dom.parser.IScannerExtensionConfiguration#support$InIdentifiers()
 	 */
 	public boolean support$InIdentifiers() {
 		return false;
 	}
 
 	/*
-	 * @see org.eclipse.cdt.internal.core.parser.scanner2.IScannerExtensionConfiguration#supportAdditionalNumericLiteralSuffixes()
+	 * @see org.eclipse.cdt.core.dom.parser.IScannerExtensionConfiguration#supportAdditionalNumericLiteralSuffixes()
 	 */
 	public char[] supportAdditionalNumericLiteralSuffixes() {
 		return null;
 	}
 
 	/*
-	 * @see org.eclipse.cdt.internal.core.parser.scanner2.IScannerExtensionConfiguration#supportMinAndMaxOperators()
+	 * @see org.eclipse.cdt.core.dom.parser.IScannerExtensionConfiguration#supportMinAndMaxOperators()
 	 */
 	public boolean supportMinAndMaxOperators() {
 		return false;
 	}
 
+	/*
+	 * @see org.eclipse.cdt.core.dom.parser.IScannerExtensionConfiguration#getAdditionalKeywords()
+	 */
+	public CharArrayIntMap getAdditionalKeywords() {
+		return null;
+	}
+
+	/*
+	 * @see org.eclipse.cdt.core.dom.parser.IScannerExtensionConfiguration#getAdditionalMacros()
+	 */
+	public CharArrayObjectMap getAdditionalMacros() {
+		return null;
+	}
+
+	/*
+	 * @see org.eclipse.cdt.core.dom.parser.IScannerExtensionConfiguration#getAdditionalPreprocessorKeywords()
+	 */
+	public CharArrayIntMap getAdditionalPreprocessorKeywords() {
+		return null;
+	}
+
 	/**
 	 * Helper method to add an object style macro to the given map.
 	 * 

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/parser/IScannerExtensionConfiguration.java

@@ -15,24 +15,81 @@ import org.eclipse.cdt.core.parser.util.CharArrayIntMap;
 import org.eclipse.cdt.core.parser.util.CharArrayObjectMap;
 
 /**
+ * Scanner extension configuration interface.
+ * 
+ * <p>
+ * This interface is not intended to be implemented directly. Clients should
+ * subclass {@link AbstractScannerExtensionConfiguration} instead.
+ * </p>
+ * <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. Please do not use this API without consulting
+ * with the CDT team.
+ * </p>
+ * 
  * @author jcamelon
  */
 public interface IScannerExtensionConfiguration {
 
+	/**
+	 * @return <code>true</code>, if macros should be initialized to 1
+	 */
 	public boolean initializeMacroValuesTo1();
+
+	/**
+	 * Support for GNU extension "Dollar Signs in Identifier Names".
+	 * 
+	 * @see http://gcc.gnu.org/onlinedocs/gcc/Dollar-Signs.html
+	 * @return <code>true</code>, if $ should be supported in identifiers
+	 */
 	public boolean support$InIdentifiers();
+
+	/**
+	 * Support for (deprecated) GNU minimum and maximum operators (<code>&lt;?</code>
+	 * and <code>&gt;?</code>).
+	 * 
+	 * @see http://gcc.gnu.org/onlinedocs/gcc/Deprecated-Features.html
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
+	 */
 	public boolean supportMinAndMaxOperators();
 
+	/**
+	 * Support for additional numeric literal suffix characters, like e.g. 'i'
+	 * and 'j' for GNU Complex number literals.
+	 * 
+	 * @see http://gcc.gnu.org/onlinedocs/gcc/Complex.html
+	 * @return an array of chars or <code>null</code>, if no additional
+	 *         suffixes should be allowed
+	 */
+	public char[] supportAdditionalNumericLiteralSuffixes();
+
+	/**
+	 * Support for additional keywords.
+	 * 
+	 * @return a mapping of keyword name to one of the constants defined in
+	 *         {@link org.eclipse.cdt.core.parser.IToken IToken} or
+	 *         <code>null</code> for no additional keywords.
+	 */
 	public CharArrayIntMap getAdditionalKeywords();
 
-    public char [] supportAdditionalNumericLiteralSuffixes();
+	/**
+	 * Support for additional macros.
+	 * 
+	 * @return a mapping of macro name to
+	 *         {@link org.eclipse.cdt.core.parser.IMacro IMacro} or
+	 *         <code>null</code> for no additional macros.
+	 */
 	public CharArrayObjectMap getAdditionalMacros();
 
 	/**
-	 * @return a mapping of preprocessor directive keyword to one of the constants defined in
+	 * Support for additional preprocessor directives.
-	 * {@link org.eclipse.cdt.core.parser.IPreprocessorDirective IPreprocessorDirective}.
 	 * 
-	 * @since 4.0
+	 * @return a mapping of preprocessor directive keyword to one of the
+	 *         constants defined in
+	 *         {@link org.eclipse.cdt.core.parser.IPreprocessorDirective IPreprocessorDirective}
+	 *         or <code>null</code> for no additional keywords.
 	 */
 	public CharArrayIntMap getAdditionalPreprocessorKeywords();
 }

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/parser/c/ICParserExtensionConfiguration.java

@@ -14,13 +14,12 @@ package org.eclipse.cdt.core.dom.parser.c;
 
 import org.eclipse.cdt.core.dom.parser.IBuiltinBindingsProvider;
 
-
 /**
  * C parser extension configuration interface.
  * 
  * <p>
- * This interface is not intended to be implemented directly.
+ * This interface is not intended to be implemented directly. Clients should
- * Clients should subclass {@link AbstractCParserExtensionConfiguration} instead.
+ * subclass {@link AbstractCParserExtensionConfiguration} instead.
  * </p>
  * <p>
  * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
@@ -38,62 +37,79 @@ public interface ICParserExtensionConfiguration {
 
 	/**
 	 * Support for GNU extension "Statements and Declarations in Expressions".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportStatementsInExpressions();
 
 	/**
 	 * Support for GNU extension "Designated Initializers".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Designated-Inits.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportGCCStyleDesignators();
 
 	/**
 	 * Support for GNU extension "Referring to a Type with typeof".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Typeof.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportTypeofUnaryExpressions();
 
 	/**
 	 * Support for GNU extension "Inquiring on Alignment of Types or Variables".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Alignment.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportAlignOfUnaryExpression();
 
 	/**
 	 * Support for Kernighan and Richie (K&R) C.
+	 * 
 	 * @return <code>true</code> if support for K&R C should be enabled
 	 */
 	public boolean supportKnRC();
 
 	/**
-	 * See http://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html
+	 * See http://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html for more
-	 * for more information on GCC's Other Built-in Symbols.
+	 * information on GCC's Other Built-in Symbols.
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * 
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 * @deprecated use {@link #getBuiltinBindingsProvider()} instead.
 	 */
 	public boolean supportGCCOtherBuiltinSymbols();
 
 	/**
-	 * See http://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html
+	 * See http://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html for more
-	 * for more information on GCC's Attribute Specifiers.
+	 * information on GCC's Attribute Specifiers.
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * 
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportAttributeSpecifiers();
 
 	/**
 	 * Win32 compiler extensions also supported by GCC on Win32
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * 
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportDeclspecSpecifiers();
 
 	/**
 	 * Provide additional built-in bindings.
-	 * @return an instance of {@link IBuiltinBindingsProvider} or <code>null</code>
+	 * 
+	 * @return an instance of {@link IBuiltinBindingsProvider} or
+	 *         <code>null</code>
 	 */
 	public IBuiltinBindingsProvider getBuiltinBindingsProvider();
 }

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/parser/cpp/ICPPParserExtensionConfiguration.java

@@ -15,13 +15,12 @@ package org.eclipse.cdt.core.dom.parser.cpp;
 import org.eclipse.cdt.core.dom.ast.IScope;
 import org.eclipse.cdt.core.dom.parser.IBuiltinBindingsProvider;
 
-
 /**
  * C++ parser extension configuration interface.
  * 
  * <p>
- * This interface is not intended to be implemented directly.
+ * This interface is not intended to be implemented directly. Clients should
- * Clients should subclass {@link AbstractCPPParserExtensionConfiguration} instead.
+ * subclass {@link AbstractCPPParserExtensionConfiguration} instead.
  * </p>
  * <p>
  * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
@@ -40,96 +39,126 @@ public interface ICPPParserExtensionConfiguration {
 
 	/**
 	 * Support for GNU extension "Restricting Pointer Aliasing".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Restricted-Pointers.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean allowRestrictPointerOperators();
 
 	/**
 	 * Support for GNU extension "Extended Syntax for Template Instantiation".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Template-Instantiation.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportExtendedTemplateSyntax();
 
 	/**
-	 * Support for (deprecated) GNU minimum and maximum operators (`<?' and `>?').
+	 * Support for (deprecated) GNU minimum and maximum operators ((<code>&lt;?</code> and
+	 * <code>&gt;?</code>). If enabled, scanner extension support for those operators must
+	 * also be enabled.
+	 * 
+	 * @see IScannerExtensionConfiguration
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Deprecated-Features.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportMinAndMaxOperators();
 
 	/**
 	 * Support for GNU extension "Data types for complex numbers".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Complex.html#Complex
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportComplexNumbers();
 
 	/**
 	 * Support for the GNU <code>__restrict__</code> keyword.
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * 
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportRestrictKeyword();
 
 	/**
 	 * Support for GNU long long types.
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Long-Long.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportLongLongs();
 
 	/**
 	 * Support for GNU extension "Statements and Declarations in Expressions".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportStatementsInExpressions();
 
 	/**
 	 * Support for GNU extension "Referring to a Type with typeof".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Typeof.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportTypeofUnaryExpressions();
 
 	/**
 	 * Support for GNU extension "Inquiring on Alignment of Types or Variables".
+	 * 
 	 * @see http://gcc.gnu.org/onlinedocs/gcc/Alignment.html
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportAlignOfUnaryExpression();
 
 	/**
 	 * Support for Kernighan and Richie (K&R) C.
+	 * 
 	 * @return <code>true</code> if support for K&R C should be enabled
 	 */
 	public boolean supportKnRC();
 
 	/**
-	 * See http://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html
+	 * See http://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html for more
-	 * for more information on GCC's Other Built-in Symbols.
+	 * information on GCC's Other Built-in Symbols.
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * 
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 * @deprecated use {@link #getBuiltinSymbolProvider(IScope)} instead.
 	 */
 	public boolean supportGCCOtherBuiltinSymbols();
 
 	/**
-	 * See http://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html
+	 * See http://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html for more
-	 * for more information on GCC's Attribute Specifiers.
+	 * information on GCC's Attribute Specifiers.
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * 
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportAttributeSpecifiers();
 
 	/**
 	 * Win32 compiler extensions also supported by GCC on Win32
-	 * @return <code>true</code> if support for the extension should be enabled
+	 * 
+	 * @return <code>true</code> if support for the extension should be
+	 *         enabled
 	 */
 	public boolean supportDeclspecSpecifiers();
 
 	/**
 	 * Provide additional built-in bindings.
-	 * @return an instance of {@link IBuiltinBindingsProvider} or <code>null</code>
+	 * 
+	 * @return an instance of {@link IBuiltinBindingsProvider} or
+	 *         <code>null</code>
 	 */
 	public IBuiltinBindingsProvider getBuiltinBindingsProvider();
 }