gnosis-algorithm: Update docstrings & package commentary

1 files changed, 43 insertions, 15 deletions

diff --git a/gnosis-algorithm.el b/gnosis-algorithm.el
index 90ea7d5..cee1d13 100644
--- a/gnosis-algorithm.el
+++ b/gnosis-algorithm.el
@@ -1,12 +1,14 @@
 ;;; gnosis-algorithm.el --- Spaced Repetition Algorithm for Gnosis  -*- lexical-binding: t; -*-
 
-;; Copyright (C) 2023  Thanos Apollo
+;; Copyright (C) 2023-2024  Thanos Apollo
 
 ;; Author: Thanos Apollo <[email protected]>
 ;; Keywords: extensions
 ;; URL: https://git.thanosapollo.org/gnosis
 ;; Version: 0.0.1
 
+;; Package-Requires: ((emacs "29.1"))
+
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
 ;; the Free Software Foundation, either version 3 of the License, or
@@ -24,9 +26,24 @@
 
 ;; Handles date calculation as well as ef & interval calculations.
 
-;; This file contains the algorithm for the spaced repetition system used in Gnosis.
-;; Gnosis algorithm is inspired by the SM-2 algorithm used in Anki, but has been
-;; modified to fit the needs of Gnosis.
+;; Gnosis implements a highly customizable algorithm, inspired by SM-2.
+;; Gnosis algorithm does not use user's subjective rating of a note to
+;; determine the next review interval, but instead uses the user's
+;; success or failure in recalling the answer of a note.
+
+;; Each gnosis note has an ef (easiness factor), which is a list of 3
+;; values.  The last value is the total ef for a note, which will be
+;; used to determine the next interval upon a successful answer recall,
+;; the second value is the ef-decrease value, this value will be
+;; subtracted from the the total ef upon failure to recall the answer of
+;; a note, the first value is the ef increase, will be added to the
+;; total ef upon a successful recall.
+
+;; Each gnosis deck has a gnosis-algorithm-ef-threshold, it's an
+;; integer value that refers to the consecutive success or failures to
+;; recall an answer.  Upon reaching the threshold, gnosis-algorithm-ef-decrease
+;; or gnosis-algorithm-ef-increase will be applied to the ef-increase or
+;; ef-decrease of note.
 
 ;;; Code:
 
@@ -34,7 +51,7 @@
 (require 'calendar)
 
 (defcustom gnosis-algorithm-interval '(1 3)
-  "Gnosis initial interval for successful reviews.
+  "Gnosis initial interval for initial successful reviews.
 
 First item: First interval,
 Second item: Second interval."
@@ -44,11 +61,9 @@ Second item: Second interval."
 (defcustom gnosis-algorithm-ef '(0.35 0.30 1.3)
   "Gnosis easiness factor.
 
-First item : Increase factor
-Second item: Decrease factor
-Third item : Starting total ef
-
-Note: Starting total ef should not be above 3.0"
+First item : Increase value
+Second item: Decrease value
+Third item : Total ef"
   :group 'gnosis
   :type '(list float))
 
@@ -57,18 +72,22 @@ Note: Starting total ef should not be above 3.0"
 
 Used to calcuate new interval for failed questions.
 
-NOTE: Do not change this value above 1"
+NOTE: This value should be less than 1.0."
   :group 'gnosis
   :type 'float)
 
 (defcustom gnosis-algorithm-ef-increase 0.1
-  "Increase ef increase value by this amount for every
+  "Value to increase ef increase value with.
+
+Increase ef-increase value by this amount for every
 `gnosis-algorithm-ef-threshold' number of successful reviews."
   :group 'gnosis
   :type 'float)
 
 (defcustom gnosis-algorithm-ef-decrease 0.2
-  "Decrease ef decrease value by this amount for every
+  "Value to decrease ef decrease value with.
+
+Decrease ef decrease value by this amount for every
 `gnosis-algorithm-ef-threshold' number of failed reviews."
   :group 'gnosis
   :type 'float)
@@ -114,7 +133,7 @@ DATE format must be given as (year month day)."
 
 (cl-defun gnosis-algorithm-next-ef (&key ef success increase decrease threshold
 					 c-successes c-failures)
-  "Returns the new EF, (increase-value decrease-value total-value)
+  "Return the new EF, (increase-value decrease-value total-value)
 
 Calculate the new e-factor given existing EF and SUCCESS, either t or nil.
 
@@ -146,7 +165,16 @@ by DECREASE."
 
 (cl-defun gnosis-algorithm-next-interval (&key last-interval ef success successful-reviews
 					       failure-factor initial-interval)
-  "Calculate next interval."
+  "Calculate next interval.
+
+LAST-INTERVAL: number of days since last review
+EF: Easiness factor
+SUCCESS: t if review was successful, nil otherwise
+SUCCESSFUL-REVIEWS: number of successful reviews
+FAILURE-FACTOR: factor to multiply last interval by if review was unsuccessful
+INITIAL-INTERVAL: list of initial intervals for initial successful
+reviews.  Will be used to determine the next interval for the first 2
+successful reviews."
   (cl-assert (< gnosis-algorithm-ff 1) "Value of `gnosis-algorithm-ff' must be lower than 1")
   ;; This should only occur in testing env or when the user has made breaking changes.
   (cl-assert (> (nth 2 ef) 1) "Total ef value must be above 1")