better godoc documentation

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`
 )
 ----
 

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

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/"
 )

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

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

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

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
 }

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