Added some more docstring and README changes

README.md

@@ -13,6 +13,8 @@
   <p>
     The missing workspace tool for clojure tools.deps projects
   </p>
+
+  [![Clojars Project](https://img.shields.io/clojars/v/com.kepler16/kmono-core.svg)](https://clojars.org/com.kepler16/kmono-core)
 </div>
 
 Kmono is a suite of tools and API's for working in Clojure (mono)repos. It aims to meet Clojure where it's at by
@@ -29,6 +31,14 @@ standalone projects too.
 - **Command Runner**: Allows executing Clojure or external commands in workspace packages
 - **Local Deps Overrides**: Allow overriding properties and `deps.edn` config during local development
 
+## Documentation
+
++ **[kmono-core](https://cljdoc.org/d/com.kepler16/kmono-core)** - The core suite of API's for working with kmono
+packages.
++ **[kmono-build](https://cljdoc.org/d/com.kepler16/kmono-build)** - A companion lib to `tools.build` which contains
+API's for building jar artifacts or simplifying the use of `tools.build` in a kmono workspace.
++ **[kmono-version](https://cljdoc.org/d/com.kepler16/kmono-version)** - A set of API's for versioning kmono packages.
+
 ## Installation
 
 #### Homebrew

packages/kmono-core/src/k16/kmono/core/graph.clj

@@ -45,7 +45,11 @@
   ```clojure
   (parallel-topo-sort {a {} b {} c {}})
   ;; => [[a c] [b]]
-  ```"
+  ```
+  
+  This is generally used to calculate the execution order of packages when
+  trying to run commands in subpackages or build/release packages in the
+  correct order."
   {:malli/schema [:=> [:cat core.schema/?PackageMap] [:maybe ?ExecOrder]]}
   [packages]
   (let [stage
@@ -93,7 +97,11 @@
   the retained packages will also be kept.
 
   This function will update the `:depends-on` and `:dependent` keys of each
-  retained package to include only other packages that still remain."
+  retained package to include only other packages that still remain.
+
+  It's generally recommended to use this function instead of writing your own
+  package filtering. If you need to write your own then you should also make
+  sure to keep the `:depends-on` and `:dependents` updated."
   ([filter-fn packages] (filter-by filter-fn {} packages))
   ([filter-fn {:keys [include-dependents]} packages]
    (let [filtered

packages/kmono-version/src/k16/kmono/version.clj

@@ -49,7 +49,7 @@
   writing your own version of this function.
 
   Other kmono-* API's only care about there being a `:version` set on a package
-  - how that field is set is up to you."
+  therefore how that field is set is up to you."
   {:malli/schema [:=> [:cat :string core.schema/?PackageMap] core.schema/?PackageMap]}
   [project-root packages]
   (let [tags (git.tags/get-sorted-tags project-root)]
@@ -63,13 +63,13 @@
          persistent!)))
 
 (defn resolve-package-changes
-  "For each pacakge try find all commits that modified files in the package
+  "For each package try find all commits that modified files in the package
   subdirectory since the last known version of the package.
 
   This works by finding commits since a tag constructed from the package name
   and version. See `k16.kmono.version/resolve-package-versions` for a
   description on how this tag is expected to be formatted.
-  
+
   Any commits found will be appended to the packages `:commits` key."
   {:malli/schema [:=> [:cat :string core.schema/?PackageMap] core.schema/?PackageMap]}
   [project-root packages]

packages/kmono-version/src/k16/kmono/version/alg/semantic.clj

@@ -16,12 +16,24 @@
   {:fix :patch
    :feat :minor})
 
-(def version-type->weight
+(def ^:private version-type->weight
   {:patch 1
    :minor 2
    :major 3})
 
-(defn version-fn [package]
+(defn version-fn
+  "A `version-fn` for `k16.kmono.version/inc-package-versions` which produces a
+  version-type of `[:patch, :minor, :major]` according to the convensions of
+  semantic commits.
+
+  - A commit message with `fix:` in the title would produce a version-type of
+  `:patch`. - A commit message with `feat:` in the title would produce a
+  version-type of `:minor`. - The presence of a bang (!) such as `fix!:` would
+  produce a version-type of `:major`.
+
+  And finally if the commit message body contained the text `BREAKING CHANGE:`
+  then this would also result in a version-type of `:major`."
+  [package]
   (reduce
    (fn [current-version-type commit]
      (let [match (match-commit commit)