Reversed removal of "Default" prefix and improved documentation

Author: d-michail

jgrapht-core/src/main/java/org/jgrapht/EdgeFactory.java

@@ -19,7 +19,16 @@
 
 /**
  * An edge factory used by graphs for creating new edges.
+ * 
+ * <p>
+ * A graph uses the edge factory to create new edge objects whenever a user calls method
+ * {@link Graph#addEdge(Object, Object)}. Users can also create the edge in user code and then use
+ * method {@link Graph#addEdge(Object, Object, Object)} to add the edge.
  *
+ * <p>
+ * Note that when used inside a {@link Graph} the edge factory must return unique objects on each
+ * call.
+ * 
  * @param <V> the graph vertex type
  * @param <E> the graph edge type
  *

jgrapht-core/src/main/java/org/jgrapht/Graph.java

@@ -458,8 +458,8 @@ public interface Graph<V, E>
 
     /**
      * Get the graph type. The graph type can be used to query for additional metadata such as
-     * whether the graph supports directed or undirected edges, self-loops, parallel-edges, weights,
-     * etc.
+     * whether the graph supports directed or undirected edges, self-loops, multiple (parallel)
+     * edges, weights, etc.
      * 
      * @return the graph type
      */

jgrapht-core/src/main/java/org/jgrapht/GraphType.java

@@ -21,10 +21,15 @@
  * A graph type.
  * 
  * <p>
- * The graph type describes various properties of a graph such as whether it is directed/undirected
- * or mixed, whether it contain self-loops (edges with the same source and target vertices), whether
- * it contain multiple (parallel) edges (multiple edges with the same source and target) and whether it is
- * weighted or not.
+ * The graph type describes various properties of a graph such as whether it is directed, undirected
+ * or mixed, whether it contain self-loops (a self-loop is an edge where the source vertex is the
+ * same as the target vertex), whether it contain multiple (parallel) edges (multiple edges which
+ * connect the same pair of vertices) and whether it is weighted or not.
+ * 
+ * <p>
+ * The type of a graph can be queried on runtime using method {@link Graph#getType()}. This way, for
+ * example, an algorithm can have different behavior based on whether the input graph is directed or
+ * undirected, etc.
  * 
  * @author Dimitrios Michail
  */

jgrapht-core/src/main/java/org/jgrapht/graph/ClassBasedEdgeFactory.java

@@ -23,6 +23,11 @@
 
 /**
  * An {@link EdgeFactory} for producing edges by using a class as a factory.
+ * 
+ * <p>
+ * Note that when used inside a {@link Graph} the factory must always return a unique object on each
+ * call. This implementation calls the no-arguments constructor of the provided class. It is the
+ * user's responsibility to make sure that the no-arguments constructor creates unique objects.
  *
  * @param <V> the graph vertex type
  * @param <E> the graph edge type
@@ -47,9 +52,6 @@ public ClassBasedEdgeFactory(Class<? extends E> edgeClass)
         this.edgeClass = edgeClass;
     }
 
-    /**
-     * @see EdgeFactory#createEdge(Object, Object)
-     */
     @Override
     public E createEdge(V source, V target)
     {

jgrapht-core/src/main/java/org/jgrapht/graph/DefaultDirectedGraph.java

@@ -21,19 +21,14 @@
 import org.jgrapht.graph.builder.*;
 
 /**
- * A directed graph. A default directed graph is a non-simple directed graph in which multiple (parallel) edges
- * between any two vertices are <i>not</i> permitted, but loops are.
- *
- * <p>
- * prefixed 'Default' to avoid name collision with the DirectedGraph interface.
- * </p>
+ * The default implementation of a directed graph. A default directed graph is a non-simple directed
+ * graph in which multiple (parallel) edges between any two vertices are <i>not</i> permitted, but
+ * loops are.
  * 
  * @param <V> the graph vertex type
  * @param <E> the graph edge type
  * 
- * @deprecated In favor of {@link DirectedGraph}
  */
-@Deprecated
 public class DefaultDirectedGraph<V, E>
     extends AbstractBaseGraph<V, E>
 {

jgrapht-core/src/main/java/org/jgrapht/graph/DefaultDirectedWeightedGraph.java

@@ -21,17 +21,15 @@
 import org.jgrapht.graph.builder.*;
 
 /**
- * A directed weighted graph. A directed weighted graph is a non-simple directed graph in which
- * multiple (parallel) edges between any two vertices are <i>not</i> permitted, but loops are. The graph has
- * weights on its edges.
+ * The default implementation of a directed weighted graph. A default directed weighted graph is a
+ * non-simple directed graph in which multiple (parallel) edges between any two vertices are
+ * <i>not</i> permitted, but loops are. The graph has weights on its edges.
  *
  * @param <V> the graph vertex type
  * @param <E> the graph edge type
  *
  * @see DefaultDirectedGraph
- * @deprecated In favor of {@link DirectedWeightedGraph}
  */
-@Deprecated
 public class DefaultDirectedWeightedGraph<V, E>
     extends DefaultDirectedGraph<V, E>
 {

jgrapht-core/src/main/java/org/jgrapht/graph/DefaultGraphType.java

@@ -26,16 +26,19 @@
  * 
  * <p>
  * The graph type describes various properties of a graph such as whether it is directed, undirected
- * or mixed, whether it contain self-loops (edges with the same source and target vertices), whether
- * it contain multiple (parallel) edges (edges with the same source and target) and whether it is
- * weighted or not.
+ * or mixed, whether it contain self-loops (a self-loop is an edge where the source vertex is the
+ * same as the target vertex), whether it contain multiple (parallel) edges (multiple edges which
+ * connect the same pair of vertices) and whether it is weighted or not.
+ * 
+ * <p>
+ * The type of a graph can be queried on runtime using method {@link Graph#getType()}. This way, for
+ * example, an algorithm can have different behavior based on whether the input graph is directed or
+ * undirected, etc.
  * 
  * @author Dimitrios Michail
  */
 public class DefaultGraphType
-    implements
-    GraphType,
-    Serializable
+    implements GraphType, Serializable
 {
     private static final long serialVersionUID = 4291049312119347474L;
 

jgrapht-core/src/main/java/org/jgrapht/graph/UndirectedGraph.java renamed to jgrapht-core/src/main/java/org/jgrapht/graph/DefaultUndirectedGraph.java

@@ -21,13 +21,14 @@
 import org.jgrapht.graph.builder.*;
 
 /**
- * An undirected graph. An undirected graph is a non-simple undirected graph in which multiple (parallel) edges
- * between any two vertices are <i>not</i> permitted, but loops are.
+ * The default implementation of an undirected graph. A default undirected graph is a non-simple
+ * undirected graph in which multiple (parallel) edges between any two vertices are <i>not</i>
+ * permitted, but loops are.
  *
  * @param <V> the graph vertex type
  * @param <E> the graph edge type
  */
-public class UndirectedGraph<V, E>
+public class DefaultUndirectedGraph<V, E>
     extends AbstractBaseGraph<V, E>
 {
     private static final long serialVersionUID = -2066644490824847621L;
@@ -37,7 +38,7 @@ public class UndirectedGraph<V, E>
      *
      * @param edgeClass class on which to base factory for edges
      */
-    public UndirectedGraph(Class<? extends E> edgeClass)
+    public DefaultUndirectedGraph(Class<? extends E> edgeClass)
     {
         this(new ClassBasedEdgeFactory<>(edgeClass));
     }
@@ -47,7 +48,7 @@ public UndirectedGraph(Class<? extends E> edgeClass)
      *
      * @param ef the edge factory of the new graph.
      */
-    public UndirectedGraph(EdgeFactory<V, E> ef)
+    public DefaultUndirectedGraph(EdgeFactory<V, E> ef)
     {
         this(ef, false);
     }
@@ -58,7 +59,7 @@ public UndirectedGraph(EdgeFactory<V, E> ef)
      * @param weighted if true the graph supports edge weights
      * @param ef the edge factory of the new graph.
      */
-    public UndirectedGraph(EdgeFactory<V, E> ef, boolean weighted)
+    public DefaultUndirectedGraph(EdgeFactory<V, E> ef, boolean weighted)
     {
         super(ef, false, false, true, weighted);
     }
@@ -71,10 +72,10 @@ public UndirectedGraph(EdgeFactory<V, E> ef, boolean weighted)
      * @param <E> the graph edge type
      * @return a builder for this kind of graph
      */
-    public static <V, E> GraphBuilder<V, E, ? extends UndirectedGraph<V, E>> createBuilder(
+    public static <V, E> GraphBuilder<V, E, ? extends DefaultUndirectedGraph<V, E>> createBuilder(
         Class<? extends E> edgeClass)
     {
-        return new GraphBuilder<>(new UndirectedGraph<>(edgeClass));
+        return new GraphBuilder<>(new DefaultUndirectedGraph<>(edgeClass));
     }
 
     /**
@@ -85,10 +86,10 @@ public UndirectedGraph(EdgeFactory<V, E> ef, boolean weighted)
      * @param <E> the graph edge type
      * @return a builder for this kind of graph
      */
-    public static <V,
-        E> GraphBuilder<V, E, ? extends UndirectedGraph<V, E>> createBuilder(EdgeFactory<V, E> ef)
+    public static <V, E> GraphBuilder<V, E, ? extends DefaultUndirectedGraph<V, E>> createBuilder(
+        EdgeFactory<V, E> ef)
     {
-        return new GraphBuilder<>(new UndirectedGraph<>(ef));
+        return new GraphBuilder<>(new DefaultUndirectedGraph<>(ef));
     }
 }
 

jgrapht-core/src/main/java/org/jgrapht/graph/UndirectedWeightedGraph.java renamed to jgrapht-core/src/main/java/org/jgrapht/graph/DefaultUndirectedWeightedGraph.java

@@ -21,15 +21,17 @@
 import org.jgrapht.graph.builder.*;
 
 /**
- * A undirected weighted graph. An undirected weighted graph is a non-simple undirected graph in
- * which multiple (parallel) edges between any two vertices are <i>not</i> permitted, but loops are. The edges
- * of a weighted undirected graph have weights.
+ * The default implementation of an undirected weighted graph. A default undirected weighted graph
+ * is a non-simple undirected graph in which multiple (parallel) edges between any two vertices are
+ * <i>not</i> permitted, but loops are. The edges of a weighted undirected graph have weights.
  * 
  * @param <V> the graph vertex type
  * @param <E> the graph edge type
+ * 
+ * @see DefaultUndirectedGraph
  */
-public class UndirectedWeightedGraph<V, E>
-    extends UndirectedGraph<V, E>
+public class DefaultUndirectedWeightedGraph<V, E>
+    extends DefaultUndirectedGraph<V, E>
 {
     private static final long serialVersionUID = -1008165881690129042L;
 
@@ -38,7 +40,7 @@ public class UndirectedWeightedGraph<V, E>
      *
      * @param ef the edge factory of the new graph.
      */
-    public UndirectedWeightedGraph(EdgeFactory<V, E> ef)
+    public DefaultUndirectedWeightedGraph(EdgeFactory<V, E> ef)
     {
         super(ef, true);
     }
@@ -48,7 +50,7 @@ public UndirectedWeightedGraph(EdgeFactory<V, E> ef)
      *
      * @param edgeClass class on which to base factory for edges
      */
-    public UndirectedWeightedGraph(Class<? extends E> edgeClass)
+    public DefaultUndirectedWeightedGraph(Class<? extends E> edgeClass)
     {
         this(new ClassBasedEdgeFactory<>(edgeClass));
     }
@@ -61,10 +63,11 @@ public UndirectedWeightedGraph(Class<? extends E> edgeClass)
      * @param <E> the graph edge type
      * @return a builder for this kind of graph
      */
-    public static <V, E> GraphBuilder<V, E, ? extends UndirectedWeightedGraph<V, E>> createBuilder(
-        Class<? extends E> edgeClass)
+    public static <V,
+        E> GraphBuilder<V, E, ? extends DefaultUndirectedWeightedGraph<V, E>> createBuilder(
+            Class<? extends E> edgeClass)
     {
-        return new GraphBuilder<>(new UndirectedWeightedGraph<>(edgeClass));
+        return new GraphBuilder<>(new DefaultUndirectedWeightedGraph<>(edgeClass));
     }
 
     /**
@@ -75,9 +78,10 @@ public UndirectedWeightedGraph(Class<? extends E> edgeClass)
      * @param <E> the graph edge type
      * @return a builder for this kind of graph
      */
-    public static <V, E> GraphBuilder<V, E, ? extends UndirectedWeightedGraph<V, E>> createBuilder(
-        EdgeFactory<V, E> ef)
+    public static <V,
+        E> GraphBuilder<V, E, ? extends DefaultUndirectedWeightedGraph<V, E>> createBuilder(
+            EdgeFactory<V, E> ef)
     {
-        return new GraphBuilder<>(new UndirectedWeightedGraph<>(ef));
+        return new GraphBuilder<>(new DefaultUndirectedWeightedGraph<>(ef));
     }
 }