Merge branch 'version-0.1.2' into master0.1.2

- Minor updates on commentary & docstrings, using checkdoc

With this version gnosis should meet the requirments to be included on
MELPA

3 files changed, 41 insertions, 11 deletions

diff --git a/gnosis-algorithm.el b/gnosis-algorithm.el
index 2dcd33d..e6a2b1f 100644
--- a/gnosis-algorithm.el
+++ b/gnosis-algorithm.el
@@ -37,7 +37,7 @@
 First item: First interval,
 Second item: Second interval.
 
-Note: gnosis-algorithm-interval is ignored after 10 TOTAL reviews or
+Note: `gnosis-algorithm-interval' is ignored after 10 TOTAL reviews or
 when ef is above > 3.0, which should only be the case for customized
 notes/review sessions."
   :group 'gnosis
@@ -48,10 +48,9 @@ notes/review sessions."
 
 First item : Increase factor
 Second item: Decrease factor
-Third item : Starting ef
+Third item : Starting total ef
 
-WARNING! Starting ef should not be above 2.5, it's recommended to keep
-it below 2.0"
+Note: Starting total ef should not be above 3.0"
   :group 'gnosis
   :type 'list)
 
@@ -101,6 +100,7 @@ The structure of the given date is (YEAR MONTH DAY)."
 ;; This should be further tested for notes with last-interval of 0 when success 0
 ;; For future versions of this algorithm, we should also calculate
 ;; failures in row to have "leech" like notes as well.
+;; TODO: Use initial-interval value instead gnosis-algorithm-interval
 (defun gnosis-algorithm-next-interval (last-interval n ef success ff successful-reviews)
   "Calculate next interval.
 - LAST-INTERVAL : The number of days since the item was last reviewed.
@@ -109,10 +109,10 @@ The structure of the given date is (YEAR MONTH DAY)."
 - SUCCESS : Success of the recall, ranges from 0 (unsuccessful) to 1
   (successful).
 - FF: Failure factor
-- SUCCESSFUL-REVIEWS : Number of successful reviews in a row.
+- SUCCESSFUL-REVIEWS : Number of successful reviews.
 
-Returns a tuple: (INTERVAL N EF) where,
-- Next review date in (year month day) format.
+Returns a list of: (INTERVAL N EF) where,
+- Next review date in (yyyy mm dd) format.
 - N : Incremented by 1.
 - EF : Modified based on the recall success for the item."
   (cl-assert (and (>= success 0)
diff --git a/gnosis-dev.el b/gnosis-dev.el
index f5003fc..4387ce9 100644
--- a/gnosis-dev.el
+++ b/gnosis-dev.el
@@ -1,6 +1,33 @@
+;;; gnosis-algorithm.el --- Gnosis development tools  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2023  Thanos Apollo
+
+;; Author: Thanos Apollo <[email protected]>
+;; Keywords: extensions
+;; URL: https://git.thanosapollo.org/gnosis
+;; Version: 0.0.1
+
+;; Package-Requires: ((emacs "27.2") (compat "29.1.4.2"))
+
+;; 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
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 ;; Random functions to make development/testing of gnosis.el easier
 
+;;; Commentary:
+
+;; Development tools used for gnosis
+
 ;;; Code:
 
 (require 'gnosis)
@@ -22,7 +49,10 @@
     selected-items))
 
 (defun gnosis-dev-add-fields (&optional num deck)
-  "Add random inputs to test."
+  "Add random inputs to test.
+
+NUM: Number of random inputs to add.
+DECK: Deck to add the inputs to."
   (let ((num (or num (string-to-number (read-string "Number of random inputs: "))))
 	(testing-deck (or deck "testing")))
     (unless (gnosis-get 'name 'decks `(= name ,testing-deck))
diff --git a/gnosis.el b/gnosis.el
index 5a288ea..752d828 100644
--- a/gnosis.el
+++ b/gnosis.el
@@ -150,7 +150,7 @@ Use `gnosis-db-init' to initialize `gnosis-db' and create essential directories.
   (emacsql gnosis-db `[:create-table ,table ,values]))
 
 (cl-defun gnosis--drop-table (table)
-  "Drop TABLE from gnosis-db."
+  "Drop TABLE from `gnosis-db'."
   (emacsql gnosis-db `[:drop-table ,table]))
 
 (cl-defun gnosis--insert-into (table values)
@@ -759,7 +759,7 @@ Optionally, add cusotm PROMPT."
     image))
 
 (defun gnosis-get-tags--unique ()
-  "Return a list of unique strings for tags in gnosis-db."
+  "Return a list of unique strings for tags in `gnosis-db'."
   (cl-loop for tags in (apply #'append (gnosis-select 'tags 'notes))
            nconc tags into all-tags
            finally return (delete-dups all-tags)))
@@ -1347,7 +1347,7 @@ review."
 (defvar gnosis-db-schema-review '([(id integer :primary-key :not-null) ;; note-id
 				   (ef integer :not-null) ;; Easiness factor
 				   (ff integer :not-null) ;; Forgetting factor
-				   (interval integer :not-null)] ;; Interval
+				   (interval integer :not-null)] ;; Initial Interval
 				  (:foreign-key [id] :references notes [id]
 						:on-delete :cascade)))