adding rustdocs

6 files changed, 89 insertions, 6 deletions

diff --git a/src/attributes/compass_point.rs b/src/attributes/compass_point.rs
index 3ebb250..6a8dbd7 100644
--- a/src/attributes/compass_point.rs
+++ b/src/attributes/compass_point.rs
@@ -15,11 +15,10 @@ pub enum CompassPoint {
     SW,
     W,
     NW,
+    /// pecifies the center of the node or port
     C,
-    // TODO: none might not be a good name
-    // The compass point "_" specifies that an appropriate side of the port adjacent to the exterior
-    // of the node should be used, if such exists. Otherwise, the center is used.
-    // If no compass point is used with a portname, the default value is "_".
+    /// specifies that an appropriate side of the port adjacent to the exterior of the node should
+    /// be used, if such exists.
     None,
 }
 
diff --git a/src/attributes/image.rs b/src/attributes/image.rs
index 360191a..17e2ef6 100644
--- a/src/attributes/image.rs
+++ b/src/attributes/image.rs
@@ -1,6 +1,10 @@
 use crate::dot::DotString;
 use std::borrow::Cow;
 
+/// Controls how an image is positioned within its containing node.
+/// Only has an effect when the image is smaller than the containing node.
+///
+/// The default is to be centered both horizontally and vertically.
 pub enum ImagePosition {
     TopLeft,
     TopCentered,
@@ -29,6 +33,24 @@ impl<'a> DotString<'a> for ImagePosition {
     }
 }
 
+/// Controls how an image fills its containing node.
+/// In general, the image is given its natural size, (cf. dpi), and the node size is made large
+/// enough to contain its image, its label, its margin, and its peripheries.
+///
+/// Its width and height will also be at least as large as its minimum width and height.
+/// If, however, fixedsize=true, the width and height attributes specify the exact size of the node.
+///
+/// During rendering, in the default case (imagescale=false), the image retains its natural size.
+///
+/// If imagescale=true, the image is uniformly scaled (i.e., its aspect ratio is preserved) to fit
+/// inside the node.
+/// At least one dimension of the image will be as large as possible given the size of the node.
+///
+/// When imagescale=width, the width of the image is scaled to fill the node width.
+///
+/// When imagescale=both, both the height and the width are scaled separately to fill the node.
+///
+/// As with the case of expansion, if imagescale=true, width and height are scaled uniformly.
 pub enum ImageScale {
     Width,
     Height,
diff --git a/src/attributes/label.rs b/src/attributes/label.rs
index e62de2b..303b449 100644
--- a/src/attributes/label.rs
+++ b/src/attributes/label.rs
@@ -1,6 +1,14 @@
 use crate::dot::DotString;
 use std::borrow::Cow;
 
+/// Justification for cluster labels.
+///
+/// Right, the label is right-justified within bounding rectangle
+/// Left, left-justified
+/// Else the label is centered.
+///
+/// Note that a subgraph inherits attributes from its parent.
+/// Thus, if the root graph sets labeljust=l, the subgraph inherits this value.
 pub enum LabelJustification {
     Left,
     Right,
@@ -17,6 +25,23 @@ impl<'a> DotString<'a> for LabelJustification {
     }
 }
 
+/// Vertical placement of labels for nodes, root graphs and clusters.
+///
+/// For graphs and clusters, only labelloc=t and labelloc=b are allowed,
+/// corresponding to placement at the top and bottom, respectively.
+///
+/// By default, root graph labels go on the bottom and cluster labels go on the top.
+///
+/// Note that a subgraph inherits attributes from its parent.
+/// Thus, if the root graph sets labelloc=b, the subgraph inherits this value.
+///
+/// For nodes, this attribute is used only when the height of the node is larger than the height
+/// of its label.
+///
+/// If labelloc=t, labelloc=c, labelloc=b, the label is aligned with the top, centered, or aligned
+/// with the bottom of the node, respectively.
+///
+/// By default, the label is vertically centered.
 pub enum LabelLocation {
     Top,
     Center,
diff --git a/src/attributes/ordering.rs b/src/attributes/ordering.rs
index 1cd13b6..27037de 100644
--- a/src/attributes/ordering.rs
+++ b/src/attributes/ordering.rs
@@ -1,6 +1,16 @@
 use crate::dot::DotString;
 use std::borrow::Cow;
 
+/// If out, then the outedges of a node, that is, edges with the node as its tail node,
+/// must appear left-to-right in the same order in which they are defined in the input.
+///
+/// If in, then the inedges of a node must appear left-to-right in the same order in which they are
+/// defined in the input.
+///
+/// If defined as a graph or subgraph attribute, the value is applied to all nodes in the graph
+/// or subgraph.
+///
+/// Note that the graph attribute takes precedence over the node attribute.
 pub enum Ordering {
     In,
     Out,
diff --git a/src/attributes/port_position.rs b/src/attributes/port_position.rs
index a492b14..8900219 100644
--- a/src/attributes/port_position.rs
+++ b/src/attributes/port_position.rs
@@ -6,6 +6,7 @@ use std::borrow::Cow;
 /// If Port is used, the corresponding node must either have record shape with one of its
 /// fields having the given portname, or have an HTML-like label, one of whose components has a
 /// PORT attribute set to portname.
+/// If no compass point is used with a portname, the default value is "_".
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub enum PortPosition {
     Port {
@@ -15,8 +16,6 @@ pub enum PortPosition {
     Compass(CompassPoint),
 }
 
-// TODO: AsRef vs this?
-// See https://github.com/Peternator7/strum/blob/96ee0a9a307ec7d1a39809fb59037bd4e11557cc/strum/src/lib.rs
 impl<'a> DotString<'a> for PortPosition {
     fn dot_string(&self) -> Cow<'a, str> {
         match self {
diff --git a/src/attributes/ratio.rs b/src/attributes/ratio.rs
index a8fbad8..1ce485a 100644
--- a/src/attributes/ratio.rs
+++ b/src/attributes/ratio.rs
@@ -1,11 +1,39 @@
 use crate::dot::DotString;
 use std::borrow::Cow;
 
+/// Sets the aspect ratio (drawing height/drawing width) for the drawing.
+/// Note that this is adjusted before the size attribute constraints are enforced.
+/// In addition, the calculations usually ignore the node sizes, so the final drawing size may only
+/// approximate what is desired.
 pub enum Ratio {
+    /// Ratio is taken as the desired aspect ratio.
+    /// Then, if the actual aspect ratio is less than the desired ratio, the drawing height is
+    /// scaled up to achieve the desired ratio; if the actual ratio is greater than that desired
+    /// ratio, the drawing width is scaled up.
     Aspect(f32),
+    /// If fill and the size attribute is set, node positions are scaled, separately in both x and y,
+    /// so that the final drawing exactly fills the specified size.
+    /// If both size values exceed the width and height of the drawing, then both coordinate values
+    /// of each node are scaled up accordingly. However, if either size dimension is smaller than
+    /// the corresponding dimension in the drawing, one dimension is scaled up so that the
+    /// final drawing has the same aspect ratio as specified by size.
+    /// Then, when rendered, the layout will be scaled down uniformly in both dimensions to fit
+    /// the given size, which may cause nodes and text to shrink as well. This may not be what
+    /// the user wants, but it avoids the hard problem of how to reposition the nodes in an
+    /// acceptable fashion to reduce the drawing size.
     Fill,
+    /// If compress and the size attribute is set, dot attempts to compress the initial
+    /// layout to fit in the given size. This achieves a tighter packing of nodes but reduces
+    /// the balance and symmetry.
     Compress,
+    /// the size attribute is set, and both the width and the height of the graph are less than
+    /// the value in size, node positions are scaled uniformly until at least one dimension
+    /// fits size exactly.
+    /// Note that this is distinct from using size as the desired size, as here the drawing is
+    /// expanded before edges are generated and all node and text sizes remain unchanged.
     Expand,
+    /// the page attribute is set and the graph cannot be drawn on a single page,
+    /// then size is set to an “ideal” value.
     Auto,
 }