Fix javadoc in org.eclipse.jgit attributes package

Change-Id: I12968f4be805266f285a518a014b8bd1d0c23bae
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>

org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attribute.java

@@ -47,9 +47,12 @@ package org.eclipse.jgit.attributes;
  * <p>
  * According to the man page, an attribute can have the following states:
  * <ul>
- * <li>Set - represented by {@link State#SET}</li>
+ * <li>Set - represented by
- * <li>Unset - represented by {@link State#UNSET}</li>
+ * {@link org.eclipse.jgit.attributes.Attribute.State#SET}</li>
- * <li>Set to a value - represented by {@link State#CUSTOM}</li>
+ * <li>Unset - represented by
+ * {@link org.eclipse.jgit.attributes.Attribute.State#UNSET}</li>
+ * <li>Set to a value - represented by
+ * {@link org.eclipse.jgit.attributes.Attribute.State#CUSTOM}</li>
  * <li>Unspecified - used to revert an attribute . This is crucial in order to
  * mark an attribute as unspecified in the attributes map and thus preventing
  * following (with lower priority) nodes from setting the attribute to a value
@@ -93,10 +96,11 @@ public final class Attribute {
 	 * @param key
 	 *            the attribute key. Should not be <code>null</code>.
 	 * @param state
-	 *            the attribute state. It should be either {@link State#SET} or
+	 *            the attribute state. It should be either
-	 *            {@link State#UNSET}. In order to create a custom value
+	 *            {@link org.eclipse.jgit.attributes.Attribute.State#SET} or
-	 *            attribute prefer the use of {@link #Attribute(String, String)}
+	 *            {@link org.eclipse.jgit.attributes.Attribute.State#UNSET}. In
-	 *            constructor.
+	 *            order to create a custom value attribute prefer the use of
+	 *            {@link #Attribute(String, String)} constructor.
 	 */
 	public Attribute(String key, State state) {
 		this(key, state, null);
@@ -127,6 +131,7 @@ public final class Attribute {
 		this(key, State.CUSTOM, value);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean equals(Object obj) {
 		if (this == obj)
@@ -147,6 +152,8 @@ public final class Attribute {
 	}
 
 	/**
+	 * Get key
+	 *
 	 * @return the attribute key (never returns <code>null</code>)
 	 */
 	public String getKey() {
@@ -154,7 +161,7 @@ public final class Attribute {
 	}
 
 	/**
-	 * Returns the state.
+	 * Return the state.
 	 *
 	 * @return the state (never returns <code>null</code>)
 	 */
@@ -163,12 +170,15 @@ public final class Attribute {
 	}
 
 	/**
+	 * Get value
+	 *
 	 * @return the attribute value (may be <code>null</code>)
 	 */
 	public String getValue() {
 		return value;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public int hashCode() {
 		final int prime = 31;
@@ -179,6 +189,7 @@ public final class Attribute {
 		return result;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		switch (state) {

org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attributes.java

@@ -64,6 +64,7 @@ public final class Attributes {
 	 * Creates a new instance
 	 *
 	 * @param attributes
+	 *            a {@link org.eclipse.jgit.attributes.Attribute}
 	 */
 	public Attributes(Attribute... attributes) {
 		if (attributes != null) {
@@ -74,6 +75,8 @@ public final class Attributes {
 	}
 
 	/**
+	 * Whether the set of attributes is empty
+	 *
 	 * @return true if the set does not contain any attributes
 	 */
 	public boolean isEmpty() {
@@ -81,7 +84,10 @@ public final class Attributes {
 	}
 
 	/**
+	 * Get the attribute with the given key
+	 *
 	 * @param key
+	 *            a {@link java.lang.String} object.
 	 * @return the attribute or null
 	 */
 	public Attribute get(String key) {
@@ -89,6 +95,8 @@ public final class Attributes {
 	}
 
 	/**
+	 * Get all attributes
+	 *
 	 * @return all attributes
 	 */
 	public Collection<Attribute> getAll() {
@@ -96,32 +104,42 @@ public final class Attributes {
 	}
 
 	/**
+	 * Put an attribute
+	 *
 	 * @param a
+	 *            an {@link org.eclipse.jgit.attributes.Attribute}
 	 */
 	public void put(Attribute a) {
 		map.put(a.getKey(), a);
 	}
 
 	/**
+	 * Remove attribute with given key
+	 *
 	 * @param key
+	 *            an attribute name
 	 */
 	public void remove(String key) {
 		map.remove(key);
 	}
 
 	/**
+	 * Whether there is an attribute with this key
+	 *
 	 * @param key
-	 * @return true if the {@link Attributes} contains this key
+	 *            key of an attribute
+	 * @return true if the {@link org.eclipse.jgit.attributes.Attributes}
+	 *         contains this key
 	 */
 	public boolean containsKey(String key) {
 		return map.containsKey(key);
 	}
 
 	/**
-	 * Returns the state.
+	 * Return the state.
 	 *
 	 * @param key
-	 *
+	 *            key of an attribute
 	 * @return the state (never returns <code>null</code>)
 	 */
 	public Attribute.State getState(String key) {
@@ -130,41 +148,63 @@ public final class Attributes {
 	}
 
 	/**
+	 * Whether the attribute is set
+	 *
 	 * @param key
-	 * @return true if the key is {@link State#SET}, false in all other cases
+	 *            a {@link java.lang.String} object.
+	 * @return true if the key is
+	 *         {@link org.eclipse.jgit.attributes.Attribute.State#SET}, false in
+	 *         all other cases
 	 */
 	public boolean isSet(String key) {
 		return (getState(key) == State.SET);
 	}
 
 	/**
+	 * Whether the attribute is unset
+	 *
 	 * @param key
-	 * @return true if the key is {@link State#UNSET}, false in all other cases
+	 *            a {@link java.lang.String} object.
+	 * @return true if the key is
+	 *         {@link org.eclipse.jgit.attributes.Attribute.State#UNSET}, false
+	 *         in all other cases
 	 */
 	public boolean isUnset(String key) {
 		return (getState(key) == State.UNSET);
 	}
 
 	/**
+	 * Whether the attribute with the given key is unspecified
+	 *
 	 * @param key
-	 * @return true if the key is {@link State#UNSPECIFIED}, false in all other
+	 *            a {@link java.lang.String} object.
-	 *         cases
+	 * @return true if the key is
+	 *         {@link org.eclipse.jgit.attributes.Attribute.State#UNSPECIFIED},
+	 *         false in all other cases
 	 */
 	public boolean isUnspecified(String key) {
 		return (getState(key) == State.UNSPECIFIED);
 	}
 
 	/**
+	 * Is this a custom attribute
+	 *
 	 * @param key
-	 * @return true if the key is {@link State#CUSTOM}, false in all other cases
+	 *            a {@link java.lang.String} object.
-	 *         see {@link #getValue(String)} for the value of the key
+	 * @return true if the key is
+	 *         {@link org.eclipse.jgit.attributes.Attribute.State#CUSTOM}, false
+	 *         in all other cases see {@link #getValue(String)} for the value of
+	 *         the key
 	 */
 	public boolean isCustom(String key) {
 		return (getState(key) == State.CUSTOM);
 	}
 
 	/**
+	 * Get attribute value
+	 *
 	 * @param key
+	 *            an attribute key
 	 * @return the attribute value (may be <code>null</code>)
 	 */
 	public String getValue(String key) {
@@ -192,6 +232,7 @@ public final class Attributes {
 		return true;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		StringBuilder buf = new StringBuilder();
@@ -206,11 +247,13 @@ public final class Attributes {
 		return buf.toString();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public int hashCode() {
 		return map.hashCode();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean equals(Object obj) {
 		if (this == obj)

org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesHandler.java

@@ -61,7 +61,8 @@ import org.eclipse.jgit.treewalk.WorkingTreeIterator;
  * The attributes handler knows how to retrieve, parse and merge attributes from
  * the various gitattributes files. Furthermore it collects and expands macro
  * expressions. The method {@link #getAttributes()} yields the ready processed
- * attributes for the current path represented by the {@link TreeWalk}
+ * attributes for the current path represented by the
+ * {@link org.eclipse.jgit.treewalk.TreeWalk}
  * <p>
  * The implementation is based on the specifications in
  * http://git-scm.com/docs/gitattributes
@@ -90,11 +91,13 @@ public class AttributesHandler {
 	private final Map<String, List<Attribute>> expansions = new HashMap<>();
 
 	/**
-	 * Create an {@link AttributesHandler} with default rules as well as merged
+	 * Create an {@link org.eclipse.jgit.attributes.AttributesHandler} with
-	 * rules from global, info and worktree root attributes
+	 * default rules as well as merged rules from global, info and worktree root
+	 * attributes
 	 *
 	 * @param treeWalk
-	 * @throws IOException
+	 *            a {@link org.eclipse.jgit.treewalk.TreeWalk}
+	 * @throws java.io.IOException
 	 */
 	public AttributesHandler(TreeWalk treeWalk) throws IOException {
 		this.treeWalk = treeWalk;
@@ -129,11 +132,12 @@ public class AttributesHandler {
 	}
 
 	/**
-	 * see {@link TreeWalk#getAttributes()}
+	 * See {@link org.eclipse.jgit.treewalk.TreeWalk#getAttributes()}
 	 *
-	 * @return the {@link Attributes} for the current path represented by the
+	 * @return the {@link org.eclipse.jgit.attributes.Attributes} for the
-	 *         {@link TreeWalk}
+	 *         current path represented by the
-	 * @throws IOException
+	 *         {@link org.eclipse.jgit.treewalk.TreeWalk}
+	 * @throws java.io.IOException
 	 */
 	public Attributes getAttributes() throws IOException {
 		String entryPath = treeWalk.getPathString();
@@ -282,7 +286,10 @@ public class AttributesHandler {
 	}
 
 	/**
+	 * Expand a macro
+	 *
 	 * @param attr
+	 *            a {@link org.eclipse.jgit.attributes.Attribute}
 	 * @param result
 	 *            contains the (recursive) expanded and merged macro attributes
 	 *            including the attribute iself

org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNode.java

@@ -63,7 +63,9 @@ public class AttributesNode {
 	/** The rules that have been parsed into this node. */
 	private final List<AttributesRule> rules;
 
-	/** Create an empty ignore node with no rules. */
+	/**
+	 * Create an empty ignore node with no rules.
+	 */
 	public AttributesNode() {
 		rules = new ArrayList<>();
 	}
@@ -73,7 +75,7 @@ public class AttributesNode {
 	 *
 	 * @param rules
 	 *            list of rules.
-	 **/
+	 */
 	public AttributesNode(List<AttributesRule> rules) {
 		this.rules = rules;
 	}
@@ -84,7 +86,7 @@ public class AttributesNode {
 	 * @param in
 	 *            input stream holding the standard ignore format. The caller is
 	 *            responsible for closing the stream.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             Error thrown when reading an ignore file.
 	 */
 	public void parse(InputStream in) throws IOException {
@@ -116,7 +118,11 @@ public class AttributesNode {
 		return new BufferedReader(new InputStreamReader(in, Constants.CHARSET));
 	}
 
-	/** @return list of all ignore rules held by this node. */
+	/**
+	 * Getter for the field <code>rules</code>.
+	 *
+	 * @return list of all ignore rules held by this node
+	 */
 	public List<AttributesRule> getRules() {
 		return Collections.unmodifiableList(rules);
 	}

org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNodeProvider.java

@@ -47,32 +47,32 @@ import java.io.IOException;
 import org.eclipse.jgit.lib.CoreConfig;
 
 /**
- * An interface used to retrieve the global and info {@link AttributesNode}s.
+ * An interface used to retrieve the global and info
+ * {@link org.eclipse.jgit.attributes.AttributesNode}s.
  *
  * @since 4.2
- *
  */
 public interface AttributesNodeProvider {
 
 	/**
-	 * Retrieve the {@link AttributesNode} that holds the information located
+	 * Retrieve the {@link org.eclipse.jgit.attributes.AttributesNode} that
-	 * in $GIT_DIR/info/attributes file.
+	 * holds the information located in $GIT_DIR/info/attributes file.
 	 *
-	 * @return the {@link AttributesNode} that holds the information located in
+	 * @return the {@link org.eclipse.jgit.attributes.AttributesNode} that holds
-	 *         $GIT_DIR/info/attributes file.
+	 *         the information located in $GIT_DIR/info/attributes file.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if an error is raised while parsing the attributes file
 	 */
 	public AttributesNode getInfoAttributesNode() throws IOException;
 
 	/**
-	 * Retrieve the {@link AttributesNode} that holds the information located
+	 * Retrieve the {@link org.eclipse.jgit.attributes.AttributesNode} that
-	 * in the global gitattributes file.
+	 * holds the information located in the global gitattributes file.
 	 *
-	 * @return the {@link AttributesNode} that holds the information located in
+	 * @return the {@link org.eclipse.jgit.attributes.AttributesNode} that holds
-	 *         the global gitattributes file.
+	 *         the information located in the global gitattributes file.
-	 * @throws IOException
+	 * @throws java.io.IOException
-	 *             IOException if an error is raised while parsing the
+	 *             java.io.IOException if an error is raised while parsing the
 	 *             attributes file
 	 * @see CoreConfig#getAttributesFile()
 	 */

org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesProvider.java

@@ -49,6 +49,8 @@ package org.eclipse.jgit.attributes;
  */
 public interface AttributesProvider {
 	/**
+	 * Get attributes
+	 *
 	 * @return the currently active attributes
 	 */
 	public Attributes getAttributes();

org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesRule.java

@@ -57,7 +57,7 @@ import org.eclipse.jgit.ignore.internal.PathMatcher;
 /**
  * A single attributes rule corresponding to one line in a .gitattributes file.
  *
- * Inspiration from: {@link FastIgnoreRule}
+ * Inspiration from: {@link org.eclipse.jgit.ignore.FastIgnoreRule}
  *
  * @since 3.7
  */
@@ -162,7 +162,9 @@ public class AttributesRule {
 	}
 
 	/**
-	 * @return True if the pattern should match directories only
+	 * Whether to match directories only
+	 *
+	 * @return {@code true} if the pattern should match directories only
 	 * @since 4.3
 	 */
 	public boolean isDirOnly() {
@@ -170,7 +172,7 @@ public class AttributesRule {
 	}
 
 	/**
-	 * Returns the attributes.
+	 * Return the attributes.
 	 *
 	 * @return an unmodifiable list of attributes (never returns
 	 *         <code>null</code>)
@@ -180,6 +182,8 @@ public class AttributesRule {
 	}
 
 	/**
+	 * Whether the pattern is only a file name and not a path
+	 *
 	 * @return <code>true</code> if the pattern is just a file name and not a
 	 *         path
 	 */
@@ -188,6 +192,8 @@ public class AttributesRule {
 	}
 
 	/**
+	 * Get the pattern
+	 *
 	 * @return The blob pattern to be used as a matcher (never returns
 	 *         <code>null</code>)
 	 */
@@ -214,6 +220,7 @@ public class AttributesRule {
 		return match;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		StringBuilder sb = new StringBuilder();

org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommand.java

@@ -50,7 +50,7 @@ import java.io.OutputStream;
  * An abstraction for JGit's builtin implementations for hooks and filters.
  * Instead of spawning an external processes to start a filter/hook and to pump
  * data from/to stdin/stdout these builtin commmands may be used. They are
- * constructed by {@link FilterCommandFactory}.
+ * constructed by {@link org.eclipse.jgit.attributes.FilterCommandFactory}.
  *
  * @since 4.6
  */
@@ -66,10 +66,12 @@ public abstract class FilterCommand {
 	protected OutputStream out;
 
 	/**
+	 * Constructor for FilterCommand
+	 *
 	 * @param in
-	 *            The {@link InputStream} this command should read from
+	 *            The {@link java.io.InputStream} this command should read from
 	 * @param out
-	 *            The {@link OutputStream} this command should write to
+	 *            The {@link java.io.OutputStream} this command should write to
 	 */
 	public FilterCommand(InputStream in, OutputStream out) {
 		this.in = in;
@@ -80,15 +82,15 @@ public abstract class FilterCommand {
 	 * Execute the command. The command is supposed to read data from
 	 * {@link #in} and to write the result to {@link #out}. It returns the
 	 * number of bytes it read from {@link #in}. It should be called in a loop
-	 * until it returns -1 signaling that the {@link InputStream} is completely
+	 * until it returns -1 signaling that the {@link java.io.InputStream} is
-	 * processed.
+	 * completely processed.
 	 *
-	 * @return the number of bytes read from the {@link InputStream} or -1. -1
+	 * @return the number of bytes read from the {@link java.io.InputStream} or
-	 *         means that the {@link InputStream} is completely processed.
+	 *         -1. -1 means that the {@link java.io.InputStream} is completely
-	 * @throws IOException
+	 *         processed.
-	 *             when {@link IOException} occured while reading from
+	 * @throws java.io.IOException
+	 *             when {@link java.io.IOException} occured while reading from
 	 *             {@link #in} or writing to {@link #out}
-	 *
 	 */
 	public abstract int run() throws IOException;
 }

org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandFactory.java

@@ -49,23 +49,25 @@ import java.io.OutputStream;
 import org.eclipse.jgit.lib.Repository;
 
 /**
- * The factory responsible for creating instances of {@link FilterCommand}.
+ * The factory responsible for creating instances of
+ * {@link org.eclipse.jgit.attributes.FilterCommand}.
  *
  * @since 4.6
  */
 public interface FilterCommandFactory {
 	/**
-	 * Create a new {@link FilterCommand}.
+	 * Create a new {@link org.eclipse.jgit.attributes.FilterCommand}.
 	 *
 	 * @param db
 	 *            the repository this command should work on
 	 * @param in
-	 *            the {@link InputStream} this command should read from
+	 *            the {@link java.io.InputStream} this command should read from
 	 * @param out
-	 *            the {@link OutputStream} this command should write to
+	 *            the {@link java.io.OutputStream} this command should write to
-	 * @return the created {@link FilterCommand}
+	 * @return the created {@link org.eclipse.jgit.attributes.FilterCommand}
-	 * @throws IOException
+	 * @throws java.io.IOException
-	 *             thrown when the command constructor throws an IOException
+	 *             thrown when the command constructor throws an
+	 *             java.io.IOException
 	 */
 	public FilterCommand create(Repository db, InputStream in,
 			OutputStream out) throws IOException;

org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandRegistry.java

@@ -59,17 +59,20 @@ public class FilterCommandRegistry {
 	private static ConcurrentHashMap<String, FilterCommandFactory> filterCommandRegistry = new ConcurrentHashMap<>();
 
 	/**
-	 * Registers a {@link FilterCommandFactory} responsible for creating
+	 * Register a {@link org.eclipse.jgit.attributes.FilterCommandFactory}
-	 * {@link FilterCommand}s for a certain command name. If the factory f1 is
+	 * responsible for creating
-	 * registered for the name "jgit://builtin/x" then a call to
+	 * {@link org.eclipse.jgit.attributes.FilterCommand}s for a certain command
-	 * <code>getCommand("jgit://builtin/x", ...)</code> will call
+	 * name. If the factory f1 is registered for the name "jgit://builtin/x"
-	 * <code>f1(...)</code> to create a new instance of {@link FilterCommand}
+	 * then a call to <code>getCommand("jgit://builtin/x", ...)</code> will call
+	 * <code>f1(...)</code> to create a new instance of
+	 * {@link org.eclipse.jgit.attributes.FilterCommand}
 	 *
 	 * @param filterCommandName
 	 *            the command name for which this factory is registered
 	 * @param factory
-	 *            the factory responsible for creating {@link FilterCommand}s
+	 *            the factory responsible for creating
-	 *            for the specified name
+	 *            {@link org.eclipse.jgit.attributes.FilterCommand}s for the
+	 *            specified name
 	 * @return the previous factory associated with <tt>commandName</tt>, or
 	 *         <tt>null</tt> if there was no mapping for <tt>commandName</tt>
 	 */
@@ -79,8 +82,8 @@ public class FilterCommandRegistry {
 	}
 
 	/**
-	 * Unregisters the {@link FilterCommandFactory} registered for the given
+	 * Unregister the {@link org.eclipse.jgit.attributes.FilterCommandFactory}
-	 * command name
+	 * registered for the given command name
 	 *
 	 * @param filterCommandName
 	 *            the FilterCommandFactory's filter command name
@@ -92,8 +95,9 @@ public class FilterCommandRegistry {
 	}
 
 	/**
-	 * Checks whether any {@link FilterCommandFactory} is registered for a given
+	 * Check whether any
-	 * command name
+	 * {@link org.eclipse.jgit.attributes.FilterCommandFactory} is registered
+	 * for a given command name
 	 *
 	 * @param filterCommandName
 	 *            the name for which the registry should be checked
@@ -104,7 +108,10 @@ public class FilterCommandRegistry {
 	}
 
 	/**
-	 * @return Set of commandNames for which a {@link FilterCommandFactory} is
+	 * Get registered filter commands
+	 *
+	 * @return Set of commandNames for which a
+	 *         {@link org.eclipse.jgit.attributes.FilterCommandFactory} is
 	 *         registered
 	 */
 	public static Set<String> getRegisteredFilterCommands() {
@@ -112,23 +119,26 @@ public class FilterCommandRegistry {
 	}
 
 	/**
-	 * Creates a new {@link FilterCommand} for the given name. A factory must be
+	 * Create a new {@link org.eclipse.jgit.attributes.FilterCommand} for the
-	 * registered for the name in advance.
+	 * given name. A factory must be registered for the name in advance.
 	 *
 	 * @param filterCommandName
-	 *            The name for which a new {@link FilterCommand} should be
+	 *            The name for which a new
+	 *            {@link org.eclipse.jgit.attributes.FilterCommand} should be
 	 *            created
 	 * @param db
 	 *            the repository this command should work on
 	 * @param in
-	 *            the {@link InputStream} this {@link FilterCommand} should read
+	 *            the {@link java.io.InputStream} this
+	 *            {@link org.eclipse.jgit.attributes.FilterCommand} should read
 	 *            from
 	 * @param out
-	 *            the {@link OutputStream} this {@link FilterCommand} should
+	 *            the {@link java.io.OutputStream} this
-	 *            write to
+	 *            {@link org.eclipse.jgit.attributes.FilterCommand} should write
+	 *            to
 	 * @return the command if a command could be created or <code>null</code> if
 	 *         there was no factory registered for that name
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 */
 	public static FilterCommand createFilterCommand(String filterCommandName,
 			Repository db, InputStream in, OutputStream out)