updating docs

.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>

README.adoc

@@ -1,6 +1,5 @@
 = libsecret/gosecret
 Brent Saner <bts@square-r00t.net>
-Last updated {localdatetime}
 :doctype: book
 :docinfo: shared
 :data-uri:
@@ -26,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:
@@ -36,13 +36,14 @@ To use this library as a replacement without significantly modifying your code,
 ----
 // ...
 replace (
-    github.com/gsterjov/go-libsecret dev => r00t2.io/gosecret v0
+	github.com/gsterjov/go-libsecret dev => r00t2.io/gosecret v0
 )
 ----
 
 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,
@@ -56,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

@@ -1,7 +1,7 @@
 // See LICENSE in source root directory for copyright and licensing information.
 
 /*
-Package libsecret is(/was originally) a fork of go-libsecret (see https://github.com/gsterjov/go-libsecret
+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
@@ -10,11 +10,13 @@ As such, hopefully this library should serve as a more effective libsecret/Secre
 
 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.
+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:
+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 (
@@ -37,6 +39,61 @@ To use the new version,
 
 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.