updating docs

.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

.idea/codeStyles/Project.xml

@@ -0,0 +1,33 @@
+<component name="ProjectCodeStyleConfiguration">
+  <code_scheme name="Project" version="173">
+    <option name="OTHER_INDENT_OPTIONS">
+      <value>
+        <option name="USE_TAB_CHARACTER" value="true" />
+        <option name="SMART_TABS" value="true" />
+      </value>
+    </option>
+    <GoCodeStyleSettings>
+      <option name="USE_BACK_QUOTES_FOR_IMPORTS" value="true" />
+      <option name="ADD_PARENTHESES_FOR_SINGLE_IMPORT" value="true" />
+      <option name="REMOVE_REDUNDANT_IMPORT_ALIASES" value="true" />
+      <option name="ADD_LEADING_SPACE_TO_COMMENTS" value="true" />
+      <option name="MOVE_ALL_STDLIB_IMPORTS_IN_ONE_GROUP" value="true" />
+      <option name="GROUP_STDLIB_IMPORTS" value="true" />
+      <option name="WRAP_COMP_LIT" value="5" />
+      <option name="WRAP_FUNC_PARAMS" value="5" />
+      <option name="WRAP_FUNC_RESULT" value="5" />
+    </GoCodeStyleSettings>
+    <XML>
+      <option name="XML_KEEP_WHITESPACES" value="true" />
+      <option name="XML_KEEP_WHITE_SPACES_INSIDE_CDATA" value="true" />
+    </XML>
+    <codeStyleSettings language="XML">
+      <option name="WRAP_ON_TYPING" value="1" />
+    </codeStyleSettings>
+    <codeStyleSettings language="go">
+      <option name="RIGHT_MARGIN" value="180" />
+      <option name="CALL_PARAMETERS_WRAP" value="5" />
+      <option name="WRAP_ON_TYPING" value="1" />
+    </codeStyleSettings>
+  </code_scheme>
+</component>

.idea/codeStyles/codeStyleConfig.xml

@@ -0,0 +1,5 @@
+<component name="ProjectCodeStyleConfiguration">
+  <state>
+    <option name="PREFERRED_PROJECT_CODE_STYLE" value="custom" />
+  </state>
+</component>

.idea/discord.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="DiscordProjectSettings">
+    <option name="show" value="PROJECT" />
+    <option name="description" value="" />
+  </component>
+</project>

.idea/gosecret.iml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="Go" enabled="true" />
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/gosecret.iml" filepath="$PROJECT_DIR$/.idea/gosecret.iml" />
+    </modules>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

README.adoc

@@ -1,6 +1,5 @@
 = libsecret/gosecret
 Brent Saner <bts@square-r00t.net>
-Last updated {localdatetime}
 :doctype: book
 :docinfo: shared
 :data-uri:
@@ -14,6 +13,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
@@ -24,6 +25,7 @@ This project is originally forked from https://github.com/gsterjov/go-libsecret[
 and as such, hopefully this library should serve as a more effective libsecret/SecretService interface.
 
 == Backwards Compatability/Drop-In Replacement Support
+
 Version series `v0.X.X` of this library promises full and non-breaking backwards 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:
@@ -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
 )
@@ -41,6 +43,7 @@ replace (
 and then run `go mod tidy`.
 
 == New Developer API
+
 Starting from `v1.0.0` onwards, entirely breaking changes can be assumed from the original project.
 
 To use the new version,
@@ -54,7 +57,70 @@ import (
 
 To reflect the absolute breaking changes, the module name changes as well from `libsecret` to `gosecret`.
 
+=== Status
+
+The new API is underway, and all functionality in V0 is present. However, It's not "complete". https://github.com/johnnybubonic/gosecret/pulls[PRs^] welcome, of course, but this will be an ongoing effort for a bit of time.
+
+== SecretService Concepts
+
+For reference:
+
+* A *`Service`* allows one to operate on/with *`Session`* objects.
+* A *`Session`* allows one to operate on/with `*Collection*` objects.
+* A `*Collection*` allows one to operate on/with `*Item*` objects.
+* An `*Item*` allows one to operate on/with `*Secrets*`.
+(`*Secrets*` are considered "terminating objects" in this model, and contain
+actual secret value(s) and metadata).
+
+Various interactions are handled by `*Prompts*`.
+
+So the object hierarchy in *theory* looks kind of like this:
+
+----
+Service
+├─ Session "A"
+│	├─ Collection "A.1"
+│	│	├─ Item "A.1.a"
+│	│	│	├─ Secret "A_1_a_I"
+│	│	│	└─ Secret "A_1_a_II"
+│	│	└─ Item "A.1.b"
+│	│		├─ Secret "A_1_b_I"
+│	│		└─ Secret "A_1_b_II"
+│	└─ Collection "A.2"
+│		├─ Item "A.2.a"
+│		│	├─ Secret "A_2_a_I"
+│		│	└─ Secret "A_2_a_II"
+│		└─ Item "A.2.b"
+│			├─ Secret "A_2_b_I"
+│			└─ Secret "A_2_b_II"
+└─ Session "B"
+	├─ Collection "B.1"
+	│	├─ Item "B.1.a"
+	│	│	├─ Secret "B_1_a_I"
+	│	│	└─ Secret "B_1_a_II"
+	│	└─ Item "B.1.b"
+	│		├─ Secret "B_1_b_I"
+	│		└─ Secret "B_1_b_II"
+	└─ Collection "B.2"#
+		├─ Item "B.2.a"
+		│	├─ Secret "B_2_a_I"
+		│	└─ Secret "B_2_a_II"
+		└─ Item "B.2.b"
+			├─ Secret "B_2_b_I"
+			└─ Secret "B_2_b_II"
+----
+
+And so on.
+
+In *practice*, however, most users will only have two Session types:
+
+* a default "system" one, and
+* a temporary one that may or may not exist, running in memory for the current login session
+
+and a single Collection, named `login` (and aliased to `default`, usually).
+
 == Usage
+
 Full documentation can be found via inline documentation. Either via the https://pkg.go.dev/r00t2.io/gosecret[pkg.go.dev documentation^] or https://pkg.go.dev/golang.org/x/tools/cmd/godoc[`godoc`^] (or `go doc`) in the source root.
 
 ////

doc.go

@@ -0,0 +1,102 @@
+// 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`.
+
+SecretService Concepts
+
+For reference:
+
+- A Service allows one to operate on/with Session objects.
+
+- A Session allows one to operate on/with Collection objects.
+
+- A Collection allows one to operate on/with Item objects.
+
+- An Item allows one to operate on/with Secrets.
+
+(Secrets are considered "terminating objects" in this model, and contain actual secret value(s) and metadata).
+
+Various interactions are handled by Prompts.
+
+So the object hierarchy in THEORY looks kind of like this:
+
+	Service
+	├─ Session "A"
+	│	├─ Collection "A.1"
+	│	│	├─ Item "A.1.a"
+	│	│	│	├─ Secret "A_1_a_I"
+	│	│	│	└─ Secret "A_1_a_II"
+	│	│	└─ Item "A.1.b"
+	│	│		├─ Secret "A_1_b_I"
+	│	│		└─ Secret "A_1_b_II"
+	│	└─ Collection "A.2"
+	│		├─ Item "A.2.a"
+	│		│	├─ Secret "A_2_a_I"
+	│		│	└─ Secret "A_2_a_II"
+	│		└─ Item "A.2.b"
+	│			├─ Secret "A_2_b_I"
+	│			└─ Secret "A_2_b_II"
+	└─ Session "B"
+		├─ Collection "B.1"
+		│	├─ Item "B.1.a"
+		│	│	├─ Secret "B_1_a_I"
+		│	│	└─ Secret "B_1_a_II"
+		│	└─ Item "B.1.b"
+		│		├─ Secret "B_1_b_I"
+		│		└─ Secret "B_1_b_II"
+		└─ Collection "B.2"#
+			├─ Item "B.2.a"
+			│	├─ Secret "B_2_a_I"
+			│	└─ Secret "B_2_a_II"
+			└─ Item "B.2.b"
+				├─ Secret "B_2_b_I"
+				└─ Secret "B_2_b_II"
+
+And so on.
+In PRACTICE, however, most users will only have two Session types
+(a default "system" one and a temporary one that may or may not exist, running in memory for the current login session)
+and a single Collection, named "login" (and aliased to "default", usually).
+
+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 libsecret