Browse Source

Fix javadoc in org.eclipse.jgit attributes package

Change-Id: I12968f4be805266f285a518a014b8bd1d0c23bae
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
stable-4.10
Matthias Sohn 7 years ago committed by David Pursehouse
parent
commit
df2bcbfb23
  1. 27
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attribute.java
  2. 61
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attributes.java
  3. 23
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesHandler.java
  4. 14
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNode.java
  5. 26
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNodeProvider.java
  6. 2
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesProvider.java
  7. 13
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesRule.java
  8. 22
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommand.java
  9. 16
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandFactory.java
  10. 48
      org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandRegistry.java

27
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>Unset - represented by {@link State#UNSET}</li>
* <li>Set to a value - represented by {@link State#CUSTOM}</li>
* <li>Set - represented by
* {@link org.eclipse.jgit.attributes.Attribute.State#SET}</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
* {@link State#UNSET}. In order to create a custom value
* attribute prefer the use of {@link #Attribute(String, String)}
* constructor.
* the attribute state. It should be either
* {@link org.eclipse.jgit.attributes.Attribute.State#SET} or
* {@link org.eclipse.jgit.attributes.Attribute.State#UNSET}. In
* 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) {

61
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
* cases
* a {@link java.lang.String} object.
* @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
* see {@link #getValue(String)} for the value of the key
* a {@link java.lang.String} object.
* @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)

23
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
* rules from global, info and worktree root attributes
* Create an {@link org.eclipse.jgit.attributes.AttributesHandler} with
* 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
* {@link TreeWalk}
* @throws IOException
* @return the {@link org.eclipse.jgit.attributes.Attributes} for the
* current path represented by the
* {@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

14
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);
}

26
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
* in $GIT_DIR/info/attributes file.
* Retrieve the {@link org.eclipse.jgit.attributes.AttributesNode} that
* holds the information located in $GIT_DIR/info/attributes file.
*
* @return the {@link AttributesNode} that holds the information located in
* $GIT_DIR/info/attributes file.
* @throws IOException
* @return the {@link org.eclipse.jgit.attributes.AttributesNode} that holds
* the information located in $GIT_DIR/info/attributes file.
* @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
* in the global gitattributes file.
* Retrieve the {@link org.eclipse.jgit.attributes.AttributesNode} that
* holds the information located in the global gitattributes file.
*
* @return the {@link AttributesNode} that holds the information located in
* the global gitattributes file.
* @throws IOException
* IOException if an error is raised while parsing the
* @return the {@link org.eclipse.jgit.attributes.AttributesNode} that holds
* the information located in the global gitattributes file.
* @throws java.io.IOException
* java.io.IOException if an error is raised while parsing the
* attributes file
* @see CoreConfig#getAttributesFile()
*/

2
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();

13
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();

22
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
* processed.
* until it returns -1 signaling that the {@link java.io.InputStream} is
* completely processed.
*
* @return the number of bytes read from the {@link InputStream} or -1. -1
* means that the {@link InputStream} is completely processed.
* @throws IOException
* when {@link IOException} occured while reading from
* @return the number of bytes read from the {@link java.io.InputStream} or
* -1. -1 means that the {@link java.io.InputStream} is completely
* processed.
* @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;
}

16
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
* @return the created {@link FilterCommand}
* @throws IOException
* thrown when the command constructor throws an IOException
* the {@link java.io.OutputStream} this command should write to
* @return the created {@link org.eclipse.jgit.attributes.FilterCommand}
* @throws java.io.IOException
* thrown when the command constructor throws an
* java.io.IOException
*/
public FilterCommand create(Repository db, InputStream in,
OutputStream out) throws IOException;

48
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
* {@link FilterCommand}s for a certain command name. If the factory f1 is
* registered for the name "jgit://builtin/x" then a call to
* <code>getCommand("jgit://builtin/x", ...)</code> will call
* <code>f1(...)</code> to create a new instance of {@link FilterCommand}
* Register a {@link org.eclipse.jgit.attributes.FilterCommandFactory}
* responsible for creating
* {@link org.eclipse.jgit.attributes.FilterCommand}s for a certain command
* name. If the factory f1 is registered for the name "jgit://builtin/x"
* 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
* for the specified name
* the factory responsible for creating
* {@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
* command name
* Unregister the {@link org.eclipse.jgit.attributes.FilterCommandFactory}
* 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
* command name
* Check whether any
* {@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
* registered for the name in advance.
* Create a new {@link org.eclipse.jgit.attributes.FilterCommand} for the
* 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
* write to
* the {@link java.io.OutputStream} this
* {@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)

Loading…
Cancel
Save