From 4eb06140d996b1a5a6ac15578089ef9f61f95663 Mon Sep 17 00:00:00 2001 From: seancarroll Date: Thu, 7 Jan 2021 22:47:41 -0600 Subject: adding rustdocs --- src/attributes/compass_point.rs | 7 +++---- src/attributes/image.rs | 22 ++++++++++++++++++++++ src/attributes/label.rs | 25 +++++++++++++++++++++++++ src/attributes/ordering.rs | 10 ++++++++++ src/attributes/port_position.rs | 3 +-- src/attributes/ratio.rs | 28 ++++++++++++++++++++++++++++ 6 files changed, 89 insertions(+), 6 deletions(-) (limited to 'src/attributes') 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, } -- cgit v1.2.3