motiejus
/
jgit
1
Fork 0
Code Releases Activity

Fix javadoc in org.eclipse.jgit attributes package 

Change-Id: I12968f4be805266f285a518a014b8bd1d0c23bae
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
This commit is contained in:
Matthias Sohn 2017-12-18 00:29:12 +01:00 committed by David Pursehouse
parent 6ac27ee215
commit df2bcbfb23
10 changed files with 171 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attribute.java
View File

@ -47,9 +47,12 @@
* <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 static enum State {
* @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 Attribute(String key, String value) {
this(key, State.CUSTOM, value);
}
/** {@inheritDoc} */
@Override
public boolean equals(Object obj) {
if (this == obj)
@ -147,6 +152,8 @@ public boolean equals(Object obj) {
}
/**
* Get key
*
* @return the attribute key (never returns <code>null</code>)
*/
public String getKey() {
@ -154,7 +161,7 @@ public String getKey() {
}
/**
* Returns the state.
* Return the state.
*
* @return the state (never returns <code>null</code>)
*/
@ -163,12 +170,15 @@ public State getState() {
}
/**
* 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 int hashCode() {
return result;
}
/** {@inheritDoc} */
@Override
public String toString() {
switch (state) {

61
org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attributes.java
View File

@ -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 Attributes(Attribute... 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 boolean isEmpty() {
}
/**
* 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 Attribute get(String key) {
}
/**
* Get all attributes
*
* @return all attributes
*/
public Collection<Attribute> getAll() {
@ -96,32 +104,42 @@ public Collection<Attribute> getAll() {
}
/**
* 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 Attribute.State getState(String key) {
}
/**
* 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 @@ && getValue(Constants.ATTR_MERGE)
return true;
}
/** {@inheritDoc} */
@Override
public String toString() {
StringBuilder buf = new StringBuilder();
@ -206,11 +247,13 @@ public String toString() {
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
View File

@ -61,7 +61,8 @@
* 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 AttributesHandler(TreeWalk treeWalk) throws IOException {
}
/**
* 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 @@ protected void mergeAttributes(@Nullable AttributesNode node,
}
/**
* 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
View File

@ -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 AttributesNode() {
*
* @param rules
* list of rules.
**/
*/
public AttributesNode(List<AttributesRule> rules) {
this.rules = rules;
}
@ -84,7 +86,7 @@ public AttributesNode(List<AttributesRule> rules) {
* @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 @@ private static BufferedReader asReader(InputStream in) {
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
View File

@ -47,32 +47,32 @@
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
View File

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

13
org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesRule.java
View File

@ -57,7 +57,7 @@
/**
* 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 AttributesRule(String pattern, String attributes) {
}
/**
* @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 boolean isDirOnly() {
}
/**
* Returns the attributes.
* Return the attributes.
*
* @return an unmodifiable list of attributes (never returns
* <code>null</code>)
@ -180,6 +182,8 @@ public List<Attribute> getAttributes() {
}
/**
* 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 boolean isNameOnly() {
}
/**
* Get the pattern
*
* @return The blob pattern to be used as a matcher (never returns
* <code>null</code>)
*/
@ -214,6 +220,7 @@ public boolean isMatch(String relativeTarget, boolean isDirectory) {
return match;
}
/** {@inheritDoc} */
@Override
public String toString() {
StringBuilder sb = new StringBuilder();

22
org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommand.java
View File

@ -50,7 +50,7 @@
* 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 FilterCommand(InputStream in, OutputStream out) {
* 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
View File

@ -49,23 +49,25 @@
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
View File

@ -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 static FilterCommandFactory register(String filterCommandName,
}
/**
* 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 static FilterCommandFactory unregister(String filterCommandName) {
}
/**
* 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 static boolean isRegistered(String filterCommandName) {
}
/**
* @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 static Set<String> getRegisteredFilterCommands() {
}
/**
* 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)