From dbc0962e469617f7ecd1a3559e4e5481d63318f8 Mon Sep 17 00:00:00 2001
From: brent s <bts@square-r00t.net>
Date: Fri, 26 Nov 2021 00:01:49 -0500
Subject: [PATCH] better godoc documentation

---
 README.adoc         |  6 ++++--
 collection_funcs.go |  4 ++--
 consts.go           | 15 ++++++++++-----
 doc.go              | 45 +++++++++++++++++++++++++++++++++++++++++++++
 item_funcs.go       |  2 +-
 prompt_funcs.go     |  2 +-
 service_funcs.go    |  2 +-
 session_funcs.go    |  2 +-
 8 files changed, 65 insertions(+), 13 deletions(-)
 create mode 100644 doc.go

diff --git a/README.adoc b/README.adoc
index 8e5d42b..c21e9ce 100644
--- a/README.adoc
+++ b/README.adoc
@@ -14,6 +14,8 @@ Last updated {localdatetime}
 :toclevels: 7
 :source-highlighter: rouge
 
+image::https://pkg.go.dev/badge/r00t2.io/gosecret.svg[link="https://pkg.go.dev/r00t2.io/gosecret"]
+
 This project is originally forked from https://github.com/gsterjov/go-libsecret[go-libsecret^] due to:
 
 * Lack of response from the developer
@@ -32,7 +34,7 @@ To use this library as a replacement without significantly modifying your code,
 .go.mod
 [source]
 ----
-# ...
+// ...
 replace (
     github.com/gsterjov/go-libsecret dev => r00t2.io/gosecret v0
 )
@@ -48,7 +50,7 @@ To use the new version,
 [source,go]
 ----
 import (
-    `r00t2.io/gosecret/v1`
+	`r00t2.io/gosecret/v1`
 )
 ----
 
diff --git a/collection_funcs.go b/collection_funcs.go
index 1f66425..9496946 100644
--- a/collection_funcs.go
+++ b/collection_funcs.go
@@ -7,7 +7,7 @@ import (
 // NewCollection returns a pointer to a new Collection based on a Dbus connection and a Dbus path.
 func NewCollection(conn *dbus.Conn, path dbus.ObjectPath) (coll *Collection, err error) {
 
-	// dbus.Conn.Names() will ALWAYS return a []0string with at least ONE element.
+	// dbus.Conn.Names() will ALWAYS return a []string with at least ONE element.
 	if conn == nil || (conn.Names() == nil || len(conn.Names()) < 1) {
 		err = ErrNoDbusConn
 		return
@@ -20,7 +20,7 @@ func NewCollection(conn *dbus.Conn, path dbus.ObjectPath) (coll *Collection, err
 
 	coll = &Collection{
 		Conn: conn,
-		Dbus: conn.Object(DBusServiceName, path),
+		Dbus: conn.Object(DbusServiceName, path),
 	}
 
 	return
diff --git a/consts.go b/consts.go
index f4b2e82..a88578d 100644
--- a/consts.go
+++ b/consts.go
@@ -1,14 +1,19 @@
 package gosecret
 
-// Libsecret/SecretService identifiers.
+// Libsecret/SecretService/Dbus identifiers.
 const (
+	// DbusServiceName is the "root Dbus path" in identifier format.
+	DbusServiceName string = "org.freedesktop.secrets"
+	// DbusItemsID is the Dbus identifier for Item.
 	DbusItemsID string = "org.freedesktop.Secret.Collection.Items"
+	// DbusCollectionDelete is the Dbus identifier for Collection.Delete.
 	DbusCollectionDelete string = "org.freedesktop.Secret.Collection.Delete"
 )
 
-// Dbus constants
+// Dbus constants and paths.
 const (
-	DBusServiceName string = "org.freedesktop.secrets"
-	DBusPath        string = "/org/freedesktop/secrets"
-	PromptPrefix    string = DBusPath + "/prompt/"
+	// DbusPath is the path version of DbusServiceName.
+	DbusPath     string = "/org/freedesktop/secrets"
+	// PromptPrefix is the path used for prompts comparison.
+	PromptPrefix string = DbusPath + "/prompt/"
 )
diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..8900972
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,45 @@
+// See LICENSE in source root directory for copyright and licensing information.
+
+/*
+Package gosecret is(/was originally) a fork of go-libsecret (see https://github.com/gsterjov/go-libsecret
+and https://pkg.go.dev/github.com/gsterjov/go-libsecret).
+
+It was forked in order to present bugfixes, actually document the library, conform to more Go-like patterns, and
+provide missing functionality (as the original seems to be unmaintained).
+As such, hopefully this library should serve as a more effective libsecret/SecretService interface.
+
+Backwards Compatibility
+
+Version series `v0.X.X` of this library promises full and non-breaking backwards compatibility/drop-in	 support of API interaction with the original project.
+The only changes should be internal optimizations, adding documentation, some file reorganizing, adding Golang module support,
+etc. -- all transparent from the library API itself.
+
+To use this library as a replacement without significantly modifying your code, you can simply use a `replace` directive in your go.mod file:
+
+	// ...
+	replace (
+		github.com/gsterjov/go-libsecret dev => r00t2.io/gosecret v0
+	)
+
+and then run `go mod tidy`.
+
+Do NOT use the master branch. For anything. I make no promises on the stability of that branch at any given time.
+New features will be added to V1 branch, and stable releases will be tagged. V0 branch is reserved only for optimization and bug fixes.
+
+New Developer API
+
+Starting from `v1.0.0` onwards, entirely breaking changes can be assumed from the original project.
+To use the new version,
+
+	import (
+		`r00t2.io/gosecret/v1`
+	)
+
+To reflect the absolute breaking changes, the module name changes as well from `libsecret` to `gosecret`.
+
+Usage
+
+Full documentation can be found via inline documentation.
+Additionally, use either https://pkg.go.dev/r00t2.io/gosecret or https://pkg.go.dev/golang.org/x/tools/cmd/godoc (or `go doc`) in the source root.
+*/
+package gosecret
diff --git a/item_funcs.go b/item_funcs.go
index cc8e3ab..b7886b6 100644
--- a/item_funcs.go
+++ b/item_funcs.go
@@ -9,7 +9,7 @@ func NewItem(conn *dbus.Conn, path dbus.ObjectPath) (item *Item) {
 
 	item = &Item{
 		Conn: conn,
-		Dbus: conn.Object(DBusServiceName, path),
+		Dbus: conn.Object(DbusServiceName, path),
 	}
 
 	return
diff --git a/prompt_funcs.go b/prompt_funcs.go
index c66e08e..3e6755e 100644
--- a/prompt_funcs.go
+++ b/prompt_funcs.go
@@ -9,7 +9,7 @@ func NewPrompt(conn *dbus.Conn, path dbus.ObjectPath) (prompt *Prompt) {
 
 	prompt = &Prompt{
 		Conn: conn,
-		Dbus: conn.Object(DBusServiceName, path),
+		Dbus: conn.Object(DbusServiceName, path),
 	}
 
 	return
diff --git a/service_funcs.go b/service_funcs.go
index 723a8f8..09c2d67 100644
--- a/service_funcs.go
+++ b/service_funcs.go
@@ -15,7 +15,7 @@ func NewService() (service *Service, err error) {
 	if service.Conn, err = dbus.SessionBus(); err != nil {
 		return
 	}
-	service.Dbus = service.Conn.Object(DBusServiceName, dbus.ObjectPath(DBusPath))
+	service.Dbus = service.Conn.Object(DbusServiceName, dbus.ObjectPath(DbusPath))
 
 	return
 }
diff --git a/session_funcs.go b/session_funcs.go
index b9046df..4ccd66c 100644
--- a/session_funcs.go
+++ b/session_funcs.go
@@ -9,7 +9,7 @@ func NewSession(conn *dbus.Conn, path dbus.ObjectPath) (session *Session) {
 
 	session = &Session{
 		Conn: conn,
-		Dbus: conn.Object(DBusServiceName, path),
+		Dbus: conn.Object(DbusServiceName, path),
 	}
 
 	return