doc: Rewrite docs for todo module parts

Signed-off-by: Matthias Beyer <mail@beyermatthias.de>

2 files changed, 83 insertions, 9 deletions

diff --git a/doc/src/04020-module-todo.md b/doc/src/04020-module-todo.md
index 3849b242..48903c91 100644
--- a/doc/src/04020-module-todo.md
+++ b/doc/src/04020-module-todo.md
@@ -1,9 +1,4 @@
 ## Todo {#sec:modules:todo}
 
-The Todo module implements `taskwarrior` functionality by integrating
-taskwarrior itself into imag.
-
-Each taskwarrior task s referenced from imag and represented as imag entry, thus
-making it linkable by other imag entries.
-
+The "todo" module implements a task manager.
 
diff --git a/doc/src/05100-lib-todo.md b/doc/src/05100-lib-todo.md
index 1109ee8d..50eedb41 100644
--- a/doc/src/05100-lib-todo.md
+++ b/doc/src/05100-lib-todo.md
@@ -1,8 +1,87 @@
 ## libimagtodo
 
-The library for the todo module.
+The library for the todo module which provides functionality to
+implement/implements a todomanager in imag.
 
-Whether this wraps `taskwarrior` or implements a todo tracking mechanism in imag
-itself is to be defined. Probably the latter.
+### Implementation details
 
+One todo entry is stored as one imag entry. The ID of the imag entry is generated by
+appending a unique ID (UUID) to "todo/".
+
+The unique ID identifies the todo entry.
+
+#### Stored data
+
+A todo entry stores the following information:
+
+* The (UU)ID of the todo entry
+* A status of the todo entry. Valid values are: "deleted", "done", "pending"
+* A "scheduled" date/datetime, can also yield an iterator
+* An optional "hidden" value, which specifies a date in the future where this
+  todo entry should show up. Relative (eg. "-5days"), 
+  to the "scheduled" date/datetime
+* An optional "due" date/datetime, relative to the "scheduled" time
+* A list of dependencies of the entry
+* A "importance"-level, config file defined (strings in an array, index used for
+  ranking them)
+* User defined value (a map of key-value string pairs)
+
+The description of the todo entry is stored as plain text.
+
+#### Data not stored
+
+Some data is explicitely _not_ stored by the library because there are other
+libraries fullfilling that purpose. These are:
+
+* Tags, which can be done with libimagentrytag
+* Category, which can be done with libimagentrycategory
+* Project belonging, which can be done with libimagentrylink (by linking to a
+  project file - note that "project" is a domain not yet implemented by imag)
+* Annotations, which can be stored with libimagentryannotation
+
+#### Header format
+
+The header partial for libimagtodo is as follows:
+
+```
+[todo]
+uuid = "string"
+status = "string"
+scheduled = "<kairos time spec>"
+hidden = "<kairos time func (optional)>"
+due = "<kairos time func (optional)>"
+depends = [ "list of uuids" ]
+importance = "string"
+uda = {}
+```
+
+#### Functionality
+
+The provided functionality of this library includes, but is not limited to:
+
+* Creating new todo entries in the store
+* Deleting todo entries from the store
+* get/retrieving todo entries from the store
+* Turning an entry into a todo entry
+* Getting todo details from an entry
+  * scheduled, due, waiting date/datetime
+  * priority
+  * UUID
+  * status
+  * An iterator over all dependend todo entries (as `StoreIdIterator`)
+* Calculating a "urgency" of a todo entry from a formula weighted by configurable factors
+
+
+#### Dependencies between tasks
+
+Dependencies between todo entries are created by putting the UUID of a dependent todo entry into
+the `todo.depends` header.
+This way, a unidirectional link is created. A link (as in `libimagentrylink`) is
+_also_ created, but this can be turned off explicitely.
+
+As `libimagentrylink` links are bidirectional, they do not suffice for todo
+entry dependency creation.
+
+As todo entries are stored with the Store IDs "todo/<uuid>", creating a
+`StoreId` from a UUID is trivial.