From ead12ce2ad93d94e9084dd4d9903a4ccd1636d65 Mon Sep 17 00:00:00 2001
From: Kevin Atkinson <k@kevina.org>
Date: Tue, 25 Sep 2018 16:33:46 -0400
Subject: [PATCH] Add documenation.

License: MIT
Signed-off-by: Kevin Atkinson <k@kevina.org>
---
 core/commands/cmdenv/cidbase.go | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/core/commands/cmdenv/cidbase.go b/core/commands/cmdenv/cidbase.go
index a0e318c8d767..1546b62afa11 100644
--- a/core/commands/cmdenv/cidbase.go
+++ b/core/commands/cmdenv/cidbase.go
@@ -12,6 +12,14 @@ import (
 var OptionCidBase = cmdkit.StringOption("cid-base", "mbase", "Multi-base to use to encode version 1 CIDs in output.")
 var OptionOutputCidV1 = cmdkit.BoolOption("output-cidv1", "Upgrade CID version 0 to version 1 in output.")
 
+// CidBaseHandler is a helper class to process the `--cid-base` and
+// `--output-cidv1` options.  In the future it may also be used to
+// process relevant config settings.
+//
+// Several of its methods return the class itself in order to allow
+// easy chaining, a typical usage would be
+// `cmdenv.NewCidBaseHandler(req).UseGlobal().Proc()` or
+// `cmdenv.NewCidBaseHandlerLegacy(req).Proc()`.
 type CidBaseHandler struct {
 	base           string
 	upgrade        bool
@@ -20,6 +28,7 @@ type CidBaseHandler struct {
 	enc            *cidenc.Encoder
 }
 
+// NewCidBaseHandler created a a CidBaseHandler from a request
 func NewCidBaseHandler(req *cmds.Request) *CidBaseHandler {
 	h := &CidBaseHandler{}
 	h.base, _ = req.Options["cid-base"].(string)
@@ -28,6 +37,8 @@ func NewCidBaseHandler(req *cmds.Request) *CidBaseHandler {
 	return h
 }
 
+// NewCidBaseHandlerLegacy created a a CidBaseHandler from a request
+// using the old commands library
 func NewCidBaseHandlerLegacy(req oldcmds.Request) *CidBaseHandler {
 	h := &CidBaseHandler{}
 	h.base, _, _ = req.Option("cid-base").String()
@@ -36,11 +47,17 @@ func NewCidBaseHandlerLegacy(req oldcmds.Request) *CidBaseHandler {
 	return h
 }
 
+// UseGlobal enables the use of the global default.  This is somewhat
+// of a hack and should be used with care.  In particular it should
+// only be used on the client side and not the server side.
 func (h *CidBaseHandler) UseGlobal() *CidBaseHandler {
 	h.enc = &cidenc.Default
 	return h
 }
 
+// Proc processes the `--cid-base` and `--output-cidv1` options.  If
+// UseGlobal was enabled it will change the value of the global
+// default.
 func (h *CidBaseHandler) Proc() (*CidBaseHandler, error) {
 	var e cidenc.Encoder = cidenc.Default
 	if h.base != "" {
@@ -63,10 +80,19 @@ func (h *CidBaseHandler) Proc() (*CidBaseHandler, error) {
 	return h, nil
 }
 
+// Encoder returns a copy of the underlying Encoder
 func (h *CidBaseHandler) Encoder() cidenc.Encoder {
 	return *h.enc
 }
 
+// EncoderFromPath returns a a new Encoder that will format Cid like
+// the one in the path if the `--cid-base` option is not used.  (If
+// the `--cid-base` is used then a copy of the base encoder will be
+// returned.)  In particular: if the path contains a version 1 CID
+// then all CIDs will be outputting using the same multibase.  if the
+// path contains a version 0 CID then version 0 CIDs will be outputted
+// as is and version1 cids will use the multibase from the base
+// encoder
 func (h *CidBaseHandler) EncoderFromPath(p string) cidenc.Encoder {
 	if h.base == "" {
 		enc, _ := cidenc.FromPath(*h.enc, p)
@@ -76,6 +102,12 @@ func (h *CidBaseHandler) EncoderFromPath(p string) cidenc.Encoder {
 	}
 }
 
+// EncoderWithOverride returns a new encoder that will use the setting
+// from the base encoder unless it is a CID that was specified on the
+// command line and the `--cid-base` option was not used.  (If the
+// `--cid-base` is used then a copy of the base encoder will be
+// returned.) In that case the same CID string as specified on the
+// command line will be used.
 func (h *CidBaseHandler) EncoderWithOverride() cidenc.Interface {
 	if h.base == "" {
 		enc := cidenc.NewOverride(*h.enc)