Javadoc for refactoring, by Mirko Stocker, bug 181493.

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/AddDeclarationNodeToClassChange.java

@@ -27,6 +27,13 @@ import org.eclipse.cdt.internal.core.dom.parser.cpp.CPPASTVisibilityLabel;
 
 import org.eclipse.cdt.internal.ui.refactoring.utils.VisibilityEnum;
 
+/**
+ * Adds a declaration to an existing class via the ModificationCollector. It automatically searches 
+ * the correct insertion point for the desired visibility.
+ * 
+ * @author Mirko Stocker
+ *
+ */
 public class AddDeclarationNodeToClassChange {
 
 	private final ICPPASTCompositeTypeSpecifier nodeClass;

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/CRefactoring.java

@@ -60,6 +60,11 @@ import org.eclipse.cdt.internal.core.dom.parser.IASTDeclarationAmbiguity;
 
 import org.eclipse.cdt.internal.ui.refactoring.utils.EclipseObjects;
 
+/**
+ * The baseclass for all other refactorings, provides some common implementations for
+ * condition checking, change generating, selection handling and translation unit loading.
+ *
+ */
 public abstract class CRefactoring extends Refactoring {
 	protected static final String EMPTY_STRING = ""; //$NON-NLS-1$
 	private static final int AST_STYLE = ITranslationUnit.AST_CONFIGURE_USING_SOURCE_CONTEXT | ITranslationUnit.AST_SKIP_INDEXED_HEADERS;

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/Container.java

@@ -11,17 +11,21 @@
  *******************************************************************************/
 package org.eclipse.cdt.internal.ui.refactoring;
 
-public class Container<T>{
+/**
+ * Simple container for one Object, with getters and setters.
+ * 
+ * @author Mirko Stocker
+ *
+ * @param <T> The type of the encapsulated node.
+ */
+public class Container<T> {
 	private T object;
 	
 	public Container(T object) {
-		super();
 		this.object = object;
 	}
 
 	public Container() {
-		super();
-		this.object = null;
 	}
 
 	public T getObject() {

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/CreateFileChange.java

@@ -27,6 +27,8 @@ import org.eclipse.ltk.core.refactoring.RefactoringStatus;
 import org.eclipse.osgi.util.NLS;
 
 /**
+ * A Change for creating a new file with the given name, content and encoding at the specified path.
+ * 
  * @author Emanuel Graf
  *
  */

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/DeleteFileChange.java

@@ -26,12 +26,14 @@ import org.eclipse.ltk.core.refactoring.Change;
 import org.eclipse.ltk.core.refactoring.RefactoringStatus;
 
 /**
+ * The counterpart to the CreateFileChange, a change to delete a file. 
+ * 
  * @author Emanuel Graf
  *
  */
 public class DeleteFileChange extends Change {
 	
-	private IPath path;
+	private final IPath path;
 	private String source;
 
 	public DeleteFileChange(IPath path) {

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/MethodContext.java

@@ -29,6 +29,11 @@ import org.eclipse.cdt.internal.core.dom.parser.ASTInternal;
 import org.eclipse.cdt.internal.core.dom.parser.cpp.CPPASTVisibilityLabel;
 import org.eclipse.cdt.internal.core.dom.parser.cpp.ICPPInternalBinding;
 
+/**
+ * Represents a function or method and adds some useful helper methods to
+ * determine if methods are in the same class.
+ *
+ */
 public class MethodContext {
 	public enum ContextType{ NONE, FUNCTION, METHOD }
 

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/ModificationCollector.java

@@ -24,10 +24,10 @@ import org.eclipse.cdt.core.dom.ast.IASTTranslationUnit;
 import org.eclipse.cdt.core.dom.rewrite.ASTRewrite;
 
 /**
- * @author Mirko Stocker
- * 
  * A ModificationCollector can be passed through a refactoring and manages the rewriters 
  * and additional changes a refactoring can create.
+ * 
+ * @author Mirko Stocker
  */
 public class ModificationCollector {
 	

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/NameNVisibilityInformation.java

@@ -15,6 +15,10 @@ import java.util.Vector;
 
 import org.eclipse.cdt.internal.ui.refactoring.utils.VisibilityEnum;
 
+/**
+ * Associate a name with a visibility and holds a list of used names.
+ *
+ */
 public class NameNVisibilityInformation {
 	
 	private String name = "";	 //$NON-NLS-1$

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/RefactoringRunner.java

@@ -17,6 +17,8 @@ import org.eclipse.ui.IWorkbenchWindow;
 import org.eclipse.ui.PlatformUI;
 
 /**
+ * Base class for all refactoring runners.
+ * 
  * @author Emanuel Graf
  *
  */

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/Visibility.java

@@ -16,6 +16,10 @@ import org.eclipse.cdt.core.dom.ast.IASTName;
 import org.eclipse.cdt.core.dom.ast.cpp.ICPPASTVisiblityLabel;
 import org.eclipse.cdt.core.dom.ast.cpp.ICPPMember;
 
+/**
+ * Represents the visibility of an IASTName.
+ * 
+ */
 public class Visibility {
 
 	/**
@@ -53,9 +57,7 @@ public class Visibility {
 	 */
 	public static final Visibility UNKNOWN = new Visibility(){ };
 	
-	
+	private Visibility(){}
-
-	private Visibility(){  }
 	
 	public static Visibility getVisibility(IASTName name){
 		try {
@@ -87,6 +89,4 @@ public class Visibility {
 	public String toString() {
 		return stringValue();
 	}
-	
-	
 }

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/dialogs/ExtractInputPage.java

@@ -28,8 +28,11 @@ import org.eclipse.cdt.internal.ui.refactoring.utils.IdentifierResult;
 import org.eclipse.cdt.internal.ui.refactoring.utils.VisibilityEnum;
 
 /**
- * @author Emanuel Graf
+ * Holds a NameAndVisibilityComposite and deals with the extract refactoring
+ * specific implementation and propagates the inputs made in the wizard ui back
+ * to the refactoring via the NameNVisibilityInformation object.
  *	
+ * @author Emanuel Graf
  */
 public abstract class ExtractInputPage extends UserInputWizardPage {
 

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/dialogs/LabeledTextField.java

@@ -19,6 +19,8 @@ import org.eclipse.swt.widgets.Label;
 import org.eclipse.swt.widgets.Text;
 
 /**
+ * A text field with an associated label, displayed side-by-side.
+ *
  * @author Mirko Stocker
  *
  */

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/dialogs/NameAndVisibilityComposite.java

@@ -25,6 +25,12 @@ import org.eclipse.swt.widgets.Text;
 
 import org.eclipse.cdt.internal.ui.refactoring.utils.VisibilityEnum;
 
+/**
+  * Composite to query for a name and visibility.
+  * 
+  * @author Thomas Corbat
+  *
+  */
 public class NameAndVisibilityComposite extends Composite {
 	
 	private LabeledTextField constantName;

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/dialogs/VisibilitySelectionPanel.java

@@ -22,6 +22,8 @@ import org.eclipse.swt.widgets.Group;
 import org.eclipse.cdt.internal.ui.refactoring.utils.VisibilityEnum;
 
 /**
+ * 3 radio buttons in a group, labeled according to the corresponding visibility name (public, private, protected).
+ * 
  * @author Thomas Corbat
  *
  */

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/extractconstant/ExtractConstantRefactoring.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007 2008 Institute for Software, HSR Hochschule fuer Technik  
+ * Copyright (c) 2007, 2008 Institute for Software, HSR Hochschule fuer Technik  
  * Rapperswil, University of applied sciences and others
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Eclipse Public License v1.0 
@@ -66,6 +66,13 @@ import org.eclipse.cdt.internal.ui.refactoring.ModificationCollector;
 import org.eclipse.cdt.internal.ui.refactoring.NameNVisibilityInformation;
 import org.eclipse.cdt.internal.ui.refactoring.utils.TranslationUnitHelper;
 
+/**
+ * The central class of the Extract Constant Refactoring. Does all the work like checking pre- and 
+ * postconditions and collecting/creating the modifications to the AST.
+ * 
+ * @author Mirko Stocker
+ *
+ */
 public class ExtractConstantRefactoring extends CRefactoring {
 	
 	private IASTLiteralExpression target = null;
@@ -107,7 +114,6 @@ public class ExtractConstantRefactoring extends CRefactoring {
 
 		if(isProgressMonitorCanceld(sm, initStatus)) return initStatus;
 		
-		//Feststellen das nur einer Markiert ist.
 		boolean oneMarked = isOneMarked(literalExpressionVector, textSelection);
 		if(!oneMarked){ 
 			//No or more than one marked
@@ -124,7 +130,6 @@ public class ExtractConstantRefactoring extends CRefactoring {
 
 		if(isProgressMonitorCanceld(sm, initStatus)) return initStatus;
 				
-		// Alle Knoten zum ersetzen finden
 		findAllNodesForReplacement(literalExpressionVector);
 		
 		info.addNamesToUsedNames(findAllDeclaredNames());

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/extractconstant/ExtractConstantRefactoringRunner.java

@@ -33,9 +33,6 @@ public class ExtractConstantRefactoringRunner extends RefactoringRunner  {
 		super(file, selection, window);
 	}
 
-
-
-
 	@Override
 	public void run() {
 		NameNVisibilityInformation info = new NameNVisibilityInformation();
@@ -57,5 +54,4 @@ public class ExtractConstantRefactoringRunner extends RefactoringRunner  {
 			CUIPlugin.getDefault().log(e);
 		}
 	}
-
 }

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/extractconstant/ExtractConstantRefactoringWizard.java

@@ -17,6 +17,9 @@ import org.eclipse.ltk.ui.refactoring.RefactoringWizard;
 import org.eclipse.cdt.internal.ui.refactoring.NameNVisibilityInformation;
 import org.eclipse.cdt.internal.ui.refactoring.dialogs.ExtractInputPage;
 
+/**
+ * The wizard page for Extract Constant Refactoring, creates the UI page.
+ */
 public class ExtractConstantRefactoringWizard extends RefactoringWizard {
 
 	private ExtractInputPage page;
@@ -33,5 +36,4 @@ public class ExtractConstantRefactoringWizard extends RefactoringWizard {
 		addPage(page);
 
 	}
-
 }

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/utils/EclipseObjects.java

@@ -11,9 +11,6 @@
  *******************************************************************************/
 package org.eclipse.cdt.internal.ui.refactoring.utils;
 
-import org.eclipse.cdt.core.dom.ast.IASTNode;
-import org.eclipse.cdt.core.model.ICElement;
-import org.eclipse.cdt.internal.ui.editor.CEditor;
 import org.eclipse.core.resources.IFile;
 import org.eclipse.core.resources.IResource;
 import org.eclipse.core.resources.ResourcesPlugin;
@@ -33,11 +30,24 @@ import org.eclipse.ui.editors.text.TextEditor;
 import org.eclipse.ui.texteditor.IDocumentProvider;
 import org.eclipse.ui.texteditor.ITextEditor;
 
+import org.eclipse.cdt.core.dom.ast.IASTNode;
+import org.eclipse.cdt.core.model.ICElement;
+
+import org.eclipse.cdt.internal.ui.editor.CEditor;
+
+/**
+ * A collection of helper methods to interact with the 
+ * workbench's IDocuments and IFiles
+ *
+ */
 public class EclipseObjects {
 	static public IWorkbenchPage getActivePage() {
-		return PlatformUI.getWorkbench().getActiveWorkbenchWindow().getActivePage();
+		return getActiveWindow().getActivePage();
 	}
 	
+	/**
+	 * @return the active, visible TextEditor
+	 */
 	static public IEditorPart getActiveEditor() {
 		IEditorPart editor = null;
 
@@ -51,6 +61,12 @@ public class EclipseObjects {
 		return editor;
 	}
 	
+	/**
+	 * Goes through all open editors to find the one with the specified file. 
+	 * 
+	 * @param file to search for
+	 * @return the editor or null
+	 */
 	static public IEditorPart getEditorForFile(IFile file) {
 		IWorkbenchPage page = getActivePage();
 		IEditorReference[] editors = page.getEditorReferences();
@@ -70,29 +86,30 @@ public class EclipseObjects {
 		return null;
 	}
 	
+	/**
+	 * @return the file from the active editor
+	 */
 	static public IFile getActiveFile(){
-		IEditorInput edi = getActiveEditor().getEditorInput();
+		IEditorInput editorInput = getActiveEditor().getEditorInput();
 
 		IFile aFile = null;
-		if(edi instanceof IFileEditorInput){
+		if(editorInput instanceof IFileEditorInput){
-			aFile = ((IFileEditorInput)edi).getFile();
+			aFile = ((IFileEditorInput)editorInput).getFile();
 		}
 		
 		return aFile;
 	}
 	
+	/**
+	 * @return the document from the currently active editor
+	 */
 	static public IDocument getActiveDocument() {
 		return getDocument( getActiveEditor() );
 	}
 	
-	static public IDocument getDocument() {
+	/**
-		ITextEditor txtEditor = ((ITextEditor)getActiveEditor());
+	 * @return the document opened in the editor 
-		if(txtEditor == null)
+	 */
-			return null;
-		IDocumentProvider prov = txtEditor.getDocumentProvider();
-		return prov.getDocument(txtEditor.getEditorInput());
-	}
-	
 	static public IDocument getDocument(IEditorPart editor) {
 		ITextEditor txtEditor = ((ITextEditor)editor);
 		IDocumentProvider prov = txtEditor.getDocumentProvider();
@@ -103,11 +120,18 @@ public class EclipseObjects {
 		return PlatformUI.getWorkbench().getActiveWorkbenchWindow();
 	}
 
+	/**
+	 * @return get the document that corresponds to the file
+	 */
 	public static IDocument getDocument(IFile file) {
 		IEditorPart editor = getEditorForFile(file);
 		return getDocument(editor);
 	}
 	
+	/**
+	 * @return return the file that contains the selection or the 
+	 * active file if there is no present selection
+	 */
 	static public IFile getFile(ISelection selection) {
 		if (selection instanceof IStructuredSelection && !selection.isEmpty()) {
 			IFile file = getFile((IStructuredSelection)selection);
@@ -132,11 +156,17 @@ public class EclipseObjects {
 		return file;
 	}
 	
+	/**
+	 * @return the file at the specified path string
+	 */
 	public static IFile getFileForPathString(String path) {
 		IPath ipath = new Path(path);
 		return ResourcesPlugin.getWorkspace().getRoot().getFileForLocation(ipath);
 	}
 	
+	/**
+	 * @return the file containing the node
+	 */
 	public static IFile getFile(IASTNode node){
 		if(node == null)
 			return null;

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/utils/FileContentHelper.java

@@ -22,7 +22,9 @@ import org.eclipse.core.runtime.CoreException;
 import org.eclipse.cdt.ui.CUIPlugin;
 
 /**
- * @author Emanuel Graf IFS
+ * Some helper methods to access part of the content of an ifile 
+ * 
+ * @author Emanuel Graf
  *
  */
 public class FileContentHelper {

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/utils/IdentifierHelper.java

@@ -17,9 +17,12 @@ import java.util.regex.Pattern;
 
 import org.eclipse.cdt.core.parser.KeywordSetKey;
 import org.eclipse.cdt.core.parser.ParserLanguage;
+
 import org.eclipse.cdt.internal.core.parser.token.KeywordSets;
 
 /**
+ * Class to verify that an identifier meets the C++ rules for valid names.
+ * 
  * @author Thomas Corbat
  *
  */
@@ -27,6 +30,10 @@ public class IdentifierHelper {
 
 	private static final String QUOTE = Messages.IdentifierHelper_quote; 
 
+	/**
+	 * @param identifier to check
+	 * @return an instance of IdentifierResult that holds the outcome of the validation
+	 */
 	public static IdentifierResult checkIdentifierName(String identifier){
 
 		if(identifier == null){

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/utils/IdentifierResult.java

@@ -14,6 +14,8 @@ package org.eclipse.cdt.internal.ui.refactoring.utils;
 
 
 /**
+ * Holds the result of a name validation, used by the IdentifierHelper.
+ * 
  * @author Thomas Corbat
  *
  */
@@ -27,8 +29,8 @@ public class IdentifierResult {
 	public static final int UNKNOWN = 5;
 	
 	
-	private int result;
+	private final int result;
-	private String message;
+	private final String message;
 	
 	public boolean isCorrect(){
 		return result == VALID;

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/utils/OffsetHelper.java

@@ -15,10 +15,13 @@ import org.eclipse.cdt.core.dom.ast.IASTFileLocation;
 import org.eclipse.cdt.core.dom.ast.IASTMacroExpansionLocation;
 import org.eclipse.cdt.core.dom.ast.IASTNode;
 import org.eclipse.cdt.core.dom.ast.IASTNodeLocation;
+
 import org.eclipse.cdt.internal.core.dom.parser.ASTNode;
 
 /**
- * @author Emanuel Graf IFS
+ * Some helper methods that calculate offsets from nodes.
+ * 
+ * @author Emanuel Graf
  *
  */
 public class OffsetHelper {

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/utils/TranslationUnitHelper.java

@@ -12,6 +12,11 @@
 
 package org.eclipse.cdt.internal.ui.refactoring.utils;
 
+import org.eclipse.core.resources.IFile;
+import org.eclipse.core.resources.ResourcesPlugin;
+import org.eclipse.core.runtime.IPath;
+import org.eclipse.core.runtime.Path;
+
 import org.eclipse.cdt.core.dom.CDOM;
 import org.eclipse.cdt.core.dom.IASTServiceProvider.UnsupportedDialectException;
 import org.eclipse.cdt.core.dom.ast.IASTDeclaration;
@@ -20,14 +25,21 @@ import org.eclipse.cdt.core.dom.ast.IASTName;
 import org.eclipse.cdt.core.dom.ast.IASTNode;
 import org.eclipse.cdt.core.dom.ast.IASTTranslationUnit;
 import org.eclipse.cdt.core.dom.ast.cpp.CPPASTVisitor;
-import org.eclipse.cdt.internal.ui.refactoring.Container;
-import org.eclipse.core.resources.IFile;
-import org.eclipse.core.resources.ResourcesPlugin;
-import org.eclipse.core.runtime.IPath;
-import org.eclipse.core.runtime.Path;
 
+import org.eclipse.cdt.internal.ui.refactoring.Container;
+
+/**
+ * A collection of methods that deal with IASTTranslationUnits.
+ * 
+ * @author Mirko Stocker
+ *
+ */
 public class TranslationUnitHelper {
 
+	/**
+	 * @param filename to load the translation unit from
+	 * @return the translation unit for the file or null
+	 */
 	public static IASTTranslationUnit loadTranslationUnit(String filename) {
 
 		if (filename != null) {
@@ -39,6 +51,10 @@ public class TranslationUnitHelper {
 		return null;
 	}
 	
+	/**
+	 * @param tmpFile to load the translation unit from
+	 * @return the translation unit for the file or null
+	 */
 	public static IASTTranslationUnit loadTranslationUnit(IFile tmpFile) {
 		if (tmpFile != null) {
 			try {
@@ -51,6 +67,9 @@ public class TranslationUnitHelper {
 		return null;
 	}
 
+	/**
+	 * Visits all names in the TU to find the specified name
+	 */
 	public static IASTName findNameInTranslationUnit(IASTTranslationUnit transUnit, IASTNode oldName) {
 		final String oldFileName = oldName.getFileLocation().getFileName();
 		final IASTFileLocation pos = oldName.getFileLocation();
@@ -77,6 +96,9 @@ public class TranslationUnitHelper {
 		return nameCon.getObject();
 	}
 	
+	/**
+	 * @return the first node in the translation unit or null
+	 */
 	public static IASTNode getFirstNode(IASTTranslationUnit unit) {
 		IASTDeclaration firstNode = null;
 		for (IASTDeclaration each : unit.getDeclarations()) {

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/refactoring/utils/VisibilityEnum.java

@@ -14,6 +14,11 @@ package org.eclipse.cdt.internal.ui.refactoring.utils;
 import org.eclipse.cdt.core.dom.ast.cpp.ICPPASTVisiblityLabel;
 import org.eclipse.cdt.core.dom.ast.cpp.ICPPASTCompositeTypeSpecifier.ICPPASTBaseSpecifier;
 
+/**
+ * Enum that represents C++ visibilities, with methods to convert to
+ * and from ICPPASTVisiblityLabel.
+ *
+ */
 public enum VisibilityEnum {
 	
 	v_public(Messages.VisibilityEnum_public),