extending the documentation for heads() based on a slack conversation (…

…#101)

* extending the documentation for heads() based on a slack conversation with additional details
* updating docs to call out implementation details and rewrite into slightly simpler sentence structures to make it easier to parse

Sources/Automerge/Document.swift

@@ -852,6 +852,23 @@ public final class Document: @unchecked Sendable {
     /// Returns a set of change hashes that represents the current state of the document.
     ///
     /// The number of change hashes in the returned set represents the number of concurrent changes the document tracks.
+    /// The heads returned are the tips of the change graph managed by Automerge, so the number of heads is the number
+    /// of concurrent changes at the tips of the graph.
+    ///
+    /// For example, if two peers make a change concurrently and sync with each other then the synced document will have two heads.
+    /// As soon as one of them makes a change on top of the synced document it will return to one head,
+    /// because the new change is not concurrent with the previous changes but causally succeeds them.
+    ///
+    /// In many ways `heads` returned by Automerge are analogous to heads in `git`
+    /// in that the hashes returned identify commits in a graph of commits.
+    /// The difference from git is that in git the heads can identify multiple points in the graph.
+    ///
+    /// Implementation details:
+    ///
+    /// The number of hashes in the document does increase linearly with the number of changes, but Automerge doesn't
+    /// encode the hashes into the output of that is provided when you invoke ``save()``.
+    /// Instead Automerge encodes the heads of the tips of the change graph and re-computes internal hashes, which means
+    /// there is no storage cost for these hashes.
     public func heads() -> Set<ChangeHash> {
         sync {
             Set(self.doc.wrapErrors { $0.heads().map { ChangeHash(bytes: $0) } })