adds documentation to some document package and rocketcomponents

core/src/net/sf/openrocket/document/Attachment.java

@@ -18,7 +18,7 @@ public abstract class Attachment extends AbstractChangeSource implements Compara
 	
 	/**
 	 * default constructor
-	 * @param name	the name of attachment
+	 * @param name	the attachment name
 	 */
 	public Attachment(String name) {
 		super();
@@ -41,6 +41,10 @@ public abstract class Attachment extends AbstractChangeSource implements Compara
 	 */
 	public abstract InputStream getBytes() throws FileNotFoundException, IOException;
 	
+	/**
+	 * {@inheritDoc}
+	 * considers only the name to equals
+	 */
 	@Override
 	public int compareTo(Attachment o) {
 		return this.name.compareTo(o.name);

core/src/net/sf/openrocket/document/DecalRegistry.java

@@ -33,7 +33,7 @@ import net.sf.openrocket.util.StateChangeListener;
 public class DecalRegistry {
 	
 	/**
-	 * default constructor
+	 * default constructor, does nothing
 	 */
 	DecalRegistry() {
 	}
@@ -41,6 +41,12 @@ public class DecalRegistry {
 	/** the decal usage map*/
 	private Map<String, DecalImageImpl> registeredDecals = new HashMap<String, DecalImageImpl>();
 	
+	/**
+	 * returns a new decal with the same image but with unique names
+	 * supports only classes and subclasses of DecalImageImpl
+	 * @param original	the decal to be made unique
+	 * @return
+	 */
 	public DecalImage makeUniqueImage(DecalImage original) {
 		
 		if (!(original instanceof DecalImageImpl)) {
@@ -66,6 +72,11 @@ public class DecalRegistry {
 		
 	}
 	
+	/**
+	 * get the image from an attachment
+	 * @param attachment
+	 * @return
+	 */
 	public DecalImage getDecalImage(Attachment attachment) {
 		String decalName = attachment.getName();
 		DecalImageImpl d;
@@ -175,6 +186,10 @@ public class DecalRegistry {
 			}
 		}
 		
+		/**
+		 * 
+		 * @return
+		 */
 		File getFileSystemLocation() {
 			return fileSystemLocation;
 		}
@@ -214,6 +229,11 @@ public class DecalRegistry {
 		
 	}
 	
+	/**
+	 * sercha
+	 * @param file
+	 * @return
+	 */
 	private DecalImageImpl findDecalForFile(File file) {
 		
 		for (DecalImageImpl d : registeredDecals.values()) {
@@ -249,19 +269,16 @@ public class DecalRegistry {
 	private static final int NUMBER_INDEX = 3;
 	private static final int EXTENSION_INDEX = 4;
 	
+	/**
+	 * Makes a unique name for saving decal files in case the name already exists
+	 * @param name	the name of the decal
+	 * @return	the name formated and unique
+	 */
 	private String makeUniqueName(String name) {
 		
-		String newName = name;
+		String newName = checkPathConsistency(name);
-		if (!newName.startsWith("decals/")) {
+		String basename = getGroup(BASE_NAME_INDEX,fileNamePattern.matcher(newName));
-			newName = "decals/" + name;
+		String extension = getGroup(EXTENSION_INDEX,fileNamePattern.matcher(newName));
-		}
-		String basename = "";
-		String extension = "";
-		Matcher nameMatcher = fileNamePattern.matcher(newName);
-		if (nameMatcher.matches()) {
-			basename = nameMatcher.group(BASE_NAME_INDEX);
-			extension = nameMatcher.group(EXTENSION_INDEX);
-		}
 		
 		Set<Integer> counts = new TreeSet<Integer>();
 		
@@ -270,7 +287,7 @@ public class DecalRegistry {
 		for (DecalImageImpl d : registeredDecals.values()) {
 			Matcher m = fileNamePattern.matcher(d.getName());
 			if (m.matches()) {
-				if (basename.equals(m.group(BASE_NAME_INDEX)) && extension.equals(m.group(EXTENSION_INDEX))) {
+				if (isofSameBaseAndExtension(m, basename, extension)) {
 					String intString = m.group(NUMBER_INDEX);
 					if (intString != null) {
 						Integer i = Integer.parseInt(intString);
@@ -287,13 +304,54 @@ public class DecalRegistry {
 			return newName;
 		}
 		
-		// find a missing integer;
+		return MessageFormat.format("{0} ({1}).{2}", basename, findMissingInteger(counts),extension);
+	}
+
+	/**
+	 * Searches the count for a new Integer
+	 * @param counts	the count set
+	 * @return	a unique integer in the count
+	 */
+	private Integer findMissingInteger(Set<Integer> counts) {
 		Integer newIndex = 1;
 		while (counts.contains(newIndex)) {
 			newIndex++;
 		}
+		return newIndex;
+	}
 
-		return MessageFormat.format("{0} ({1}).{2}", basename, newIndex, extension);
+	/**
+	 * Tests if a matcher has the same basename and extension
+	 * @param m			the matcher being tested
+	 * @param basename	the basename
+	 * @param extension	the extension
+	 * @return
+	 */
+	private boolean isofSameBaseAndExtension(Matcher m, String basename, String extension) {
+		return basename.equals(m.group(BASE_NAME_INDEX)) && extension.equals(m.group(EXTENSION_INDEX));
+	}
+	
+	/**
+	 * gets the String group from a matcher
+	 * @param index		the index of the group to
+	 * @param matcher	the matcher for the search
+	 * @return the String according with the group, empty if there's no match
+	 */
+	private String getGroup(int index, Matcher matcher) {
+		if (matcher.matches()) 
+			return matcher.group(index);
+		return "";
+	}
+
+	/**
+	 * checks if the name starts with "decals/"
+	 * @param name	the name being checked
+	 * @return	the name complete with the starting folder
+	 */
+	private String checkPathConsistency(String name){
+		if (name.startsWith("decals/")) 
+			return	name;
+		return "decals/" + name;
 	}
 	
 }

core/src/net/sf/openrocket/document/OpenRocketDocument.java

@@ -102,36 +102,56 @@ public class OpenRocketDocument implements ComponentChangeListener {
 	
 	private final List<DocumentChangeListener> listeners = new ArrayList<DocumentChangeListener>();
 	
+	/**
+	 * main constructor, enable events in the rocket 
+	 * and initializes the document 
+	 * @param rocket	the rocket to be used in the document
+	 */
 	OpenRocketDocument(Rocket rocket) {
 		this.rocket = rocket;
 		rocket.enableEvents();
 		init();
 	}
 	
+	/**
+	 * initializes the document, clearing the undo cache and
+	 * setting itself as a listener for changes in the rocket
+	 */
 	private void init() {
 		clearUndo();
-		
 		rocket.addComponentChangeListener(this);
 	}
 	
+	/**
+	 * adds a customExpression into the list
+	 * @param expression	the expression to be added
+	 */
 	public void addCustomExpression(CustomExpression expression) {
 		if (customExpressions.contains(expression)) {
 			log.info(Markers.USER_MARKER, "Could not add custom expression " + expression.getName() + " to document as document alerady has a matching expression.");
-		} else {
+		} 
 		customExpressions.add(expression);
 	}
-	}
 	
+	/**
+	 * remves
+	 * @param expression
+	 */
 	public void removeCustomExpression(CustomExpression expression) {
 		customExpressions.remove(expression);
 	}
 	
+	//TODO:LOW:this leaves the object custom expression exposed, is it supposed to be like that?
+	/**
+	 * 
+	 * @return
+	 */
 	public List<CustomExpression> getCustomExpressions() {
 		return customExpressions;
 	}
 	
-	/*
+	/**
-	 * Returns a set of all the flight data types defined or available in any way in the rocket document
+	 * @returns a set of all the flight data types defined or available in any way in the rocket document
 	 */
 	public Set<FlightDataType> getFlightDataTypes() {
 		Set<FlightDataType> allTypes = new LinkedHashSet<FlightDataType>();
@@ -158,28 +178,50 @@ public class OpenRocketDocument implements ComponentChangeListener {
 		return allTypes;
 	}
 	
-	
+	/**
+	 * gets the rocket in the document
+	 * @return	the rocket in the document
+	 */
 	public Rocket getRocket() {
 		return rocket;
 	}
 	
-	
+	/**
+	 * returns the selected configuration from the rocket
+	 * @return	selected configuration from the rocket
+	 */
 	public FlightConfiguration getSelectedConfiguration() {
 		return rocket.getSelectedConfiguration();
 	}
 	
+	/**
+	 * returns the File handler object for the document
+	 * @return	the File handler object for the document
+	 */
 	public File getFile() {
 		return file;
 	}
 	
+	/**
+	 * set the file handler object for the document
+	 * @param file	the new file handler object
+	 */
 	public void setFile(File file) {
 		this.file = file;
 	}
 	
+	/**
+	 * returns if the current rocket is saved
+	 * @return	if the current rocket is saved
+	 */
 	public boolean isSaved() {
 		return rocket.getModID() == savedID;
 	}
 	
+	/**
+	 * sets the current rocket as saved, and none if false is given
+	 * @param saved	if the current rocket or none will be set to save
+	 */
 	public void setSaved(boolean saved) {
 		if (saved == false)
 			this.savedID = -1;
@@ -197,33 +239,57 @@ public class OpenRocketDocument implements ComponentChangeListener {
 	}
 	
 	
+	/**
+	 * returns the decal list used in the document
+	 * @return	the decal list registered in the document
+	 */
 	public Collection<DecalImage> getDecalList() {
 		
 		return decalRegistry.getDecalList();
 		
 	}
 	
+	/**
+	 * returns the number of times the given decal was used
+	 * @param img	the decal to be counted
+	 * @return		the number of times 
+	 */
 	public int countDecalUsage(DecalImage img) {
 		int count = 0;
 		
 		Iterator<RocketComponent> it = rocket.iterator();
 		while (it.hasNext()) {
-			RocketComponent comp = it.next();
+			if(hasDecal(it.next(),img))
-			Appearance a = comp.getAppearance();
-			if (a == null) {
-				continue;
-			}
-			Decal d = a.getTexture();
-			if (d == null) {
-				continue;
-			}
-			if (img.equals(d.getImage())) {
 				count++;
 		}
-		}
 		return count;
 	}
 	
+	//TODO: LOW: move this method to rocketComponent, Appearance and decal
+	//I see 3 layers of object accessed, seems unsafe
+	/**
+	 * checks if a rocket component has the given decalImage
+	 * @param comp	the RocketComponent to be searched
+	 * @param img	the DecalImage to be checked
+	 * @return	if the comp has img
+	 */
+	private boolean hasDecal(RocketComponent comp, DecalImage img){
+		Appearance a = comp.getAppearance();
+		if(a == null)
+			return false;
+		Decal d = a.getTexture();
+		if(d == null)
+			return false;
+		if(img.equals(d.getImage()))
+			return true;
+		return false;
+	}
+	
+	/**
+	 * gets a unique identification for the given decal
+	 * @param img	the decal to be made unique
+	 * @return		the new unique decal
+	 */
 	public DecalImage makeUniqueDecal(DecalImage img) {
 		if (countDecalUsage(img) <= 1) {
 			return img;
@@ -231,26 +297,54 @@ public class OpenRocketDocument implements ComponentChangeListener {
 		return decalRegistry.makeUniqueImage(img);
 	}
 	
+	/**
+	 * gets the decal image from an attachment
+	 * @param a	the attachment
+	 * @return	the image from the attachment
+	 */
 	public DecalImage getDecalImage(Attachment a) {
 		return decalRegistry.getDecalImage(a);
 	}
 	
+	/**
+	 * gets a list of simulations in the document
+	 * @return	the simulations in the document
+	 */
 	public List<Simulation> getSimulations() {
 		return simulations.clone();
 	}
 	
+	/**
+	 * gets the number of simulations in the document
+	 * @return	the number of simulations in the document
+	 */
 	public int getSimulationCount() {
 		return simulations.size();
 	}
 	
+	/**
+	 * the the Nth simulation from the document
+	 * @param n	simulation index
+	 * @return	the Nth simulation from the document, null if there's none
+	 */
 	public Simulation getSimulation(int n) {
 		return simulations.get(n);
 	}
 	
+	/**
+	 * gets the index of the given simulation
+	 * @param simulation	the simulation being searched
+	 * @return				the index of the simulation in the document
+	 */
 	public int getSimulationIndex(Simulation simulation) {
 		return simulations.indexOf(simulation);
 	}
 	
+	/**
+	 * adds simulation into the document
+	 * fires document change event
+	 * @param simulation	the simulation to be added
+	 */
 	public void addSimulation(Simulation simulation) {
 		simulations.add(simulation);
 		FlightConfigurationId simId = simulation.getId();
@@ -260,33 +354,61 @@ public class OpenRocketDocument implements ComponentChangeListener {
 		fireDocumentChangeEvent(new SimulationChangeEvent(simulation));
 	}
 	
+	/**
+	 * adds the simulation to the Nth index, overwriting if there is already one
+	 * fires change document event
+	 * @param simulation	the simulation to be added
+	 * @param n				the index to be added
+	 */
 	public void addSimulation(Simulation simulation, int n) {
 		simulations.add(n, simulation);
 		fireDocumentChangeEvent(new SimulationChangeEvent(simulation));
 	}
 	
+	/**
+	 * removes the specific simulation from the list
+	 * @param simulation	the simulation to be removed
+	 */
 	public void removeSimulation(Simulation simulation) {
 		simulations.remove(simulation);
 		fireDocumentChangeEvent(new SimulationChangeEvent(simulation));
 	}
 	
+	/**
+	 * removes the Nth simulation from the document
+	 * fires document change event
+	 * @param n	the Nth simulation
+	 * @return	the removed simulation
+	 */
 	public Simulation removeSimulation(int n) {
 		Simulation simulation = simulations.remove(n);
 		fireDocumentChangeEvent(new SimulationChangeEvent(simulation));
 		return simulation;
 	}
 	
+	/**
+	 * removes the flight configuration and simulation with the specific id
+	 * @param configId
+	 */
 	public void removeFlightConfigurationAndSimulations(FlightConfigurationId configId) {
 		if (configId == null) {
 			return;
 		}
+		removeSimulations(configId);
+		rocket.removeFlightConfiguration(configId);
+	}
+
+	/**
+	 * removes all simulations with the specific configId
+	 * @param configId	the Flight Configuration Id that dictates which simulations shoul be removed
+	 */
+	private void removeSimulations(FlightConfigurationId configId) {
 		for (Simulation s : getSimulations()) {
 			// Assumes modifiable collection - which it is
 			if (configId.equals(s.getId())) {
 				removeSimulation(s);
 			}
 		}
-		rocket.removeFlightConfiguration(configId);
 	}
 	
 	
@@ -331,42 +453,22 @@ public class OpenRocketDocument implements ComponentChangeListener {
 	 */
 	public void addUndoPosition(String description) {
 		
-		if (storedDescription != null) {
+		checkDescription(description);
-			logUndoError("addUndoPosition called while storedDescription=" + storedDescription +
-					" description=" + description);
-		}
 		
 		// Check whether modifications have been done since last call
-		if (isCleanState()) {
+		if(isCheckNoModification(description))
-			// No modifications
-			log.info("Adding undo position '" + description + "' to " + this + ", document was in clean state");
-			nextDescription = description;
 			return;
-		}
-		
 		log.info("Adding undo position '" + description + "' to " + this + ", document is in unclean state");
+		checkUndoPositionConsistency();
+		addStateToUndoHistory(description);
 		
-		/*
+		maintainMaximumUndoSize();
-		 * Modifications have been made to the rocket.  We should be at the end of the
+	}
-		 * undo history, but check for consistency and try to recover.
+
+	/**
+	 * 
 	 */
-		if (undoPosition != undoHistory.size() - 1) {
+	private void maintainMaximumUndoSize() {
-			logUndoError("undo position inconsistency");
-		}
-		while (undoPosition < undoHistory.size() - 1) {
-			undoHistory.removeLast();
-			undoDescription.removeLast();
-		}
-		
-		
-		// Add the current state to the undo history
-		undoHistory.add(rocket.copyWithOriginalID());
-		undoDescription.add(null);
-		nextDescription = description;
-		undoPosition++;
-		
-		
-		// Maintain maximum undo size
 		if (undoHistory.size() > UNDO_LEVELS + UNDO_MARGIN && undoPosition > UNDO_MARGIN) {
 			for (int i = 0; i < UNDO_MARGIN; i++) {
 				undoHistory.removeFirst();
@@ -376,6 +478,57 @@ public class OpenRocketDocument implements ComponentChangeListener {
 		}
 	}
 
+	/**
+	 * @param description
+	 */
+	private void addStateToUndoHistory(String description) {
+		// Add the current state to the undo history
+		undoHistory.add(rocket.copyWithOriginalID());
+		undoDescription.add(null);
+		nextDescription = description;
+		undoPosition++;
+	}
+
+	/**
+	 * checks if there was or not modification, and logs
+	 * 
+	 * @param description	the description to be used in the log
+	 * @return	if there was or not modification
+	 */
+	private boolean isCheckNoModification(String description){
+		if (isCleanState()) {
+			// No modifications
+			log.info("Adding undo position '" + description + "' to " + this + ", document was in clean state");
+			nextDescription = description;
+			return true;
+		}
+		return false;
+	}
+	
+	/**
+	 * checks if the document already has a stored undo description
+	 * logs if it has
+	 * 
+	 * @param description	undo description to be logged
+	 */
+	private void checkDescription(String description) {
+		if (storedDescription != null) {
+			logUndoError("addUndoPosition called while storedDescription=" + storedDescription +
+					" description=" + description);
+		}
+	}
+
+	/**
+	 * If modifications have been made to the rocket.  We should be at the end of the
+	 * undo history, but check for consistency and try to recover.
+	 */
+	private void checkUndoPositionConsistency() {
+		if (undoPosition != undoHistory.size() - 1) {
+			logUndoError("undo position inconsistency");
+		}
+		removeRedoInfo();
+	}
+	
 	
 	/**
 	 * Start a time-limited undoable operation.  After the operation {@link #stopUndo()}
@@ -436,17 +589,28 @@ public class OpenRocketDocument implements ComponentChangeListener {
 						" undoPosition=" + undoPosition + " undoHistory.size=" + undoHistory.size() +
 						" isClean=" + isCleanState());
 			}
-			// Remove any redo information if available
+			removeRedoInfo();
+			setLatestDescription();
+		}
+		
+		fireUndoRedoChangeEvent();
+	}
+
+	/**
+	 * Sets the latest description
+	 */
+	private void setLatestDescription() {
+		undoDescription.set(undoPosition, nextDescription);
+	}
+
+	/**
+	 * Removes any redo information if available
+	 */
+	private void removeRedoInfo() {
 		while (undoPosition < undoHistory.size() - 1) {
 			undoHistory.removeLast();
 			undoDescription.removeLast();
 		}
-			
-			// Set the latest description
-			undoDescription.set(undoPosition, nextDescription);
-		}
-		
-		fireUndoRedoChangeEvent();
 	}
 	
 	
@@ -610,6 +774,7 @@ public class OpenRocketDocument implements ComponentChangeListener {
 		undoRedoListeners.remove(listener);
 	}
 	
+	
 	private void fireUndoRedoChangeEvent() {
 		UndoRedoListener[] array = undoRedoListeners.toArray(new UndoRedoListener[0]);
 		for (UndoRedoListener l : array) {

core/src/net/sf/openrocket/document/attachments/FileSystemAttachment.java

@@ -8,19 +8,38 @@ import java.io.InputStream;
 
 import net.sf.openrocket.document.Attachment;
 
+/**
+ * 
+ * 	defines a file system attachment
+ *	stores the attachment location
+ */
 public class FileSystemAttachment extends Attachment {
-	
+	/** the file location*/
 	private final File location;
 	
+	/**
+	 * main constructor,
+	 * 
+	 * @param name		name of attachment
+	 * @param location	File location of attachment
+	 */
 	public FileSystemAttachment(String name, File location) {
 		super(name);
 		this.location = location;
 	}
 	
+	/**
+	 * 
+	 * @return	the File object with the attachment location
+	 */
 	public File getLocation() {
 		return location;
 	}
 	
+	/**
+	 *	{@inheritDoc}
+	 *	creates the stream based on the location passed while building
+	 */
 	@Override
 	public InputStream getBytes() throws FileNotFoundException, IOException {
 		return new FileInputStream(location);

core/src/net/sf/openrocket/rocketcomponent/FlightConfigurationId.java

@@ -2,7 +2,7 @@ package net.sf.openrocket.rocketcomponent;
 
 import java.util.UUID;
 
-/*
+/**
  * FlightConfigurationID is a very minimal wrapper class used to identify a given flight configuration for various components and options.  
  * It is intended to provide better visibility and traceability by more specific type safety -- this class replaces a 
  * straight-up <code>String</code> Key in previous implementations. 
@@ -19,10 +19,17 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
 	public final static FlightConfigurationId ERROR_FCID = new FlightConfigurationId( FlightConfigurationId.ERROR_UUID);
 	public final static FlightConfigurationId DEFAULT_VALUE_FCID = new FlightConfigurationId( FlightConfigurationId.DEFAULT_VALUE_UUID ); 
 	
+	/**
+	 * default constructor, builds with an unique random ID
+	 */
 	public FlightConfigurationId() {
 		this(UUID.randomUUID());
 	}
 	
+	/**
+	 * builds the id with the given String
+	 * @param _str	te string to be made into the id
+	 */
 	public FlightConfigurationId(final String _str) {
 		UUID candidate;
 		if(_str == null || "".equals(_str)){
@@ -37,6 +44,10 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
 		this.key = candidate;
 	}
 	
+	/**
+	 * builds he id with the given UUID object
+	 * @param _val	the UUID to be made into the id
+	 */
 	public FlightConfigurationId(final UUID _val) {
 		if (null == _val){
 			this.key = FlightConfigurationId.ERROR_UUID;
@@ -45,6 +56,10 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
 		}
 	}
 	
+	/**
+	 * {@inheritDoc}
+	 * considers equals ids with the same key
+	 */
 	@Override
 	public boolean equals(Object anObject) {
 		if (!(anObject instanceof FlightConfigurationId)) {
@@ -55,32 +70,65 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
 		return this.key.equals(otherFCID.key);
 	}
 	
+	/**
+	 * 
+	 * @return
+	 */
 	public String toShortKey(){
-		if( hasError() ){
+		if( hasError() )
 			return FlightConfigurationId.ERROR_KEY_NAME;
-		}else if( this.key == FlightConfigurationId.DEFAULT_VALUE_UUID){
+		if( isDefaultId())
 			return FlightConfigurationId.DEFAULT_VALUE_NAME;
-		}else{
 		return this.key.toString().substring(0,8);
-		}
+		
 	}
 
+	//extracted this method because maybe, just maybe, this info could be used somewhere else
+	/**
+	 * gets if the id is the default
+	 * @return	if the id is default
+	 */
+	private boolean isDefaultId() {
+		return this.key == FlightConfigurationId.DEFAULT_VALUE_UUID;
+	}
+	
+	/**
+	 * returns the whole key in the id
+	 * @return	the full key of the id
+	 */
 	public String toFullKey(){
-		return this.key.toString();
+		return this.toString();
 	}
 	
+	/**
+	 * {@inheritDoc}
+	 * uses the key hash code
+	 */
 	@Override
 	public int hashCode() {
 		return this.key.hashCode();
 	}
 
+	/**
+	 * checks if the key is the ERROR_UUID flag
+	 * @return	if the id has error
+	 */
 	public boolean hasError(){
 		return (ERROR_UUID == this.key);
 	}
+	
+	/**
+	 * checks if the key from the id is valid
+	 * @return	if the id is valid or not
+	 */
 	public boolean isValid() {
 		return !hasError();
 	}
 	
+	/**
+	 * {@inheritDoc}
+	 * same as get full id
+	 */
 	@Override
 	public String toString() {
 		return this.key.toString();
@@ -91,6 +139,10 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
 		return this.key.compareTo( other.key);
 	}
 	
+	/**
+	 * used for debuggin, gets the short key
+	 * @return	the short key version of the id
+	 */
 	public String toDebug(){
 		return this.toShortKey();
 	}

core/src/net/sf/openrocket/rocketcomponent/RocketComponent.java

@@ -355,6 +355,10 @@ public abstract class RocketComponent implements ChangeSource, Cloneable, Iterab
 		}
 	}
 	
+	/**
+	 * appends the debug string of the component into the passed builder
+	 * @param sb	String builder to be appended
+	 */
 	private void toDebugString(StringBuilder sb) {
 		sb.append(this.getClass().getSimpleName()).append('@').append(System.identityHashCode(this));
 		sb.append("[\"").append(this.getName()).append('"');
@@ -962,6 +966,10 @@ public abstract class RocketComponent implements ChangeSource, Cloneable, Iterab
 		return result;
 	}
 	
+	/**
+	 * returns the axial offset of the component
+	 * @return	
+	 */
 	public double getAxialOffset() {
 		mutex.verify();
 		return this.asPositionValue(this.relativePosition);
@@ -2085,6 +2093,7 @@ public abstract class RocketComponent implements ChangeSource, Cloneable, Iterab
 		}
 	}
 
+	/// debug functions
 	public String toDebugName(){
 		return this.getName()+"<"+this.getClass().getSimpleName()+">("+this.getID().substring(0,8)+")";
 	}