From 5dde9bfd1f3c2e69d18b07ecc8893840479206f6 Mon Sep 17 00:00:00 2001
From: Martin Czygan <martin.czygan@gmail.com>
Date: Wed, 31 Mar 2021 02:07:41 +0200
Subject: update docs

---
 skate/schema.go | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/skate/schema.go b/skate/schema.go
index 30a1c81..e09b7f9 100644
--- a/skate/schema.go
+++ b/skate/schema.go
@@ -227,14 +227,16 @@ type BiblioRef struct {
 	TargetCSL              string `json:"target_csl,omitempty"`
 }
 
-// ClusterResult results.
+// ClusterResult, a list of match candidates. This is typically serialized as a
+// single JSON line.
 type ClusterResult struct {
 	Key    string     `json:"k"`
 	Values []*Release `json:"v"`
 }
 
 // NonRef returns the first non-reference release found in a cluster, or an
-// error, if none has been found.
+// error, if none has been found. This depends on converted references using
+// the status "ref" in extra.
 func (cr *ClusterResult) OneNonRef() (*Release, error) {
 	for _, re := range cr.Values {
 		if re.Extra.Skate.Status != "ref" {
@@ -244,7 +246,8 @@ func (cr *ClusterResult) OneNonRef() (*Release, error) {
 	return nil, fmt.Errorf("no reference/release found")
 }
 
-// Group is a cluster with explicit groups (e.g. store the json lines in A, B).
+// Group is a cluster with explicit groups. The content is unparsed, e.g. it
+// can contain raw json strings.
 type Group struct {
 	Key string
 	A   []string
@@ -275,22 +278,29 @@ type IDList struct {
 	OL    string `json:"ol,omitempty"`
 }
 
+// IsZero returns true, if none of the identifiers is defined.
 func (l *IDList) IsZero() bool {
 	return l.ISBN == "" && l.DOI == "" && l.PMID == "" && l.ISSN == "" &&
 		l.JSTOR == "" && l.PMC == "" && l.ARXIV == "" && l.OL == ""
 }
 
+// ParseIDList parses out the identifiers from a citation document.
 func (c *MinimalCitations) ParseIDList() (result IDList) {
 	if len(c.IDList) < 3 {
 		return result
 	}
-	s := c.IDList[1 : len(c.IDList)-1]
-	parts := strings.Split(s, ",")
+	var (
+		s     = c.IDList[1 : len(c.IDList)-1] // get rid of "{" and "}"
+		parts = strings.Split(s, ",")
+		pair  []string
+	)
 	for _, part := range parts {
-		pair := strings.Split(part, "=")
+		pair = strings.Split(part, "=")
 		if len(pair) != 2 {
 			continue
 		}
+		pair[0] = strings.TrimSpace(pair[0])
+		pair[1] = strings.TrimSpace(pair[1])
 		switch pair[0] {
 		case "ISBN":
 			result.ISBN = pair[1]
-- 
cgit v1.2.3