graph/encoding/dot: refactor quoting docs (#797)

graph/encoding/dot/decode.go

@@ -44,9 +44,7 @@ type PortSetter interface {
 // If the number of graphs encoded in data is not one, an error is returned and
 // dst will hold the first graph in data.
 //
-// Attributes and IDs are quoted if needed during marshalling, to conform with
+// Attributes and IDs are unquoted during unmarshalling if appropriate.
-// valid DOT syntax. Quoted IDs and attributes are unquoted during unmarshaling,
-// so the data is kept in raw form.
 func Unmarshal(data []byte, dst encoding.Builder) error {
 	file, err := dot.ParseBytes(data)
 	if err != nil {
@@ -64,9 +62,7 @@ func Unmarshal(data []byte, dst encoding.Builder) error {
 // If the number of graphs encoded in data is not one, an error is returned and
 // dst will hold the first graph in data.
 //
-// Attributes and IDs are quoted if needed during marshalling, to conform with
+// Attributes and IDs are unquoted during unmarshalling if appropriate.
-// valid DOT syntax. Quoted IDs and attributes are unquoted during unmarshaling,
-// so the data is kept in raw form.
 func UnmarshalMulti(data []byte, dst encoding.MultiBuilder) error {
 	file, err := dot.ParseBytes(data)
 	if err != nil {

graph/encoding/dot/doc.go

@@ -11,4 +11,11 @@
 //
 // DOT grammar: http://www.graphviz.org/doc/info/lang.html
 //
+// Attribute quoting
+//
+// Attributes and IDs are quoted if needed during marshalling, to conform with
+// valid DOT syntax. Quoted IDs and attributes are unquoted during unmarshaling,
+// so the data is kept in raw form. As an exception, quoted text with a leading
+// `"<` and a trailing `>"` is not unquoted to ensure preservation of the string
+// during a round-trip.
 package dot // import "gonum.org/v1/gonum/graph/encoding/dot"

graph/encoding/dot/dot.go

@@ -1,5 +0,0 @@
-// Copyright ©2015 The Gonum Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-package dot

graph/encoding/dot/encode.go

@@ -93,9 +93,7 @@ type MultiSubgrapher interface {
 // implementation of the Node, Attributer, Porter, Attributers, Structurer,
 // Subgrapher and Graph interfaces.
 //
-// Attributes and IDs are quoted if needed during marshalling, to conform with
+// Attributes and IDs are quoted if needed during marshalling.
-// valid DOT syntax. Quoted IDs and attributes are unquoted during unmarshaling,
-// so the data is kept in raw form.
 func Marshal(g graph.Graph, name, prefix, indent string) ([]byte, error) {
 	var p simpleGraphPrinter
 	p.indent = indent
@@ -118,9 +116,7 @@ func Marshal(g graph.Graph, name, prefix, indent string) ([]byte, error) {
 // implementation of the Node, Attributer, Porter, Attributers, Structurer,
 // MultiSubgrapher and Multigraph interfaces.
 //
-// Attributes and IDs are quoted if needed during marshalling, to conform with
+// Attributes and IDs are quoted if needed during marshalling.
-// valid DOT syntax. Quoted IDs and attributes are unquoted during unmarshaling,
-// so the data is kept in raw form.
 func MarshalMulti(g graph.Multigraph, name, prefix, indent string) ([]byte, error) {
 	var p multiGraphPrinter
 	p.indent = indent