[elpa] externals/assess 0d079db1a7 34/95: Completed documentation.

[ELPA Syncer]

branch: externals/assess
commit 0d079db1a74af6a6f6ca694688c267af3df846b0
Author: Phillip Lord <phillip.lord@russet.org.uk>
Commit: Phillip Lord <phillip.lord@russet.org.uk>

    Completed documentation.
---
 sisyphus.el | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 54 insertions(+), 6 deletions(-)

diff --git a/sisyphus.el b/sisyphus.el
index 850f4fef10..c9da968320 100644
--- a/sisyphus.el
+++ b/sisyphus.el
@@ -787,13 +787,16 @@ the copy of FILE will be in a different directory."
 
 ;; ** Font-Lock
 
-;; Set up a buffer from string or file, font-lock it, test it.
-
-;; We need to define some functionality for testing font-lock.
-
-;; API below -- so we can define functionality that works generally over a 
list,
-;; and automatically coerce an item to a list.
+;; Here we define two predicates that can be used to checking
+;; fontification/syntax highlighting; as with indentation, one accepts strings
+;; but requires an explicit mode, while the other reads from file and depends 
on
+;; the normal Emacs mechanisms for defining the mode. These two are
+;; `sisyphus-font-at=' and `sisyphus-file-font-at='. Both of these have the 
same
+;; interface and have attached explainer functions. Here, we show examples with
+;; `sisyphus-face-at='.
 
+;; The simplest use is to specify a point location and a face. This returns 
true
+;; if at least that face is present at the location.
 
 ;; #+begin_src elisp
 ;;    (sisyphus-face-at=
@@ -801,7 +804,12 @@ the copy of FILE will be in a different directory."
 ;;     'emacs-lisp-mode
 ;;     2
 ;;     'font-lock-keyword-face)
+;; #+end_src
+
+;; It is also possible to specify several locations in a list, with a single
+;; face. This checks that the given font is present at every location.
 
+;; #+begin_src elisp
 ;;    (sisyphus-face-at=
 ;;     "(defun x ())
 ;; (defun y ())
@@ -809,14 +817,45 @@ the copy of FILE will be in a different directory."
 ;;     'emacs-lisp-mode
 ;;     '(2 15 28)
 ;;     'font-lock-keyword-face)
+;; #+end_src
 
+;; Or, we can specify a list of faces in which case the locations and faces are
+;; checked in a pairwise manner.
+
+;; #+begin_src elisp
 ;;    (sisyphus-face-at=
 ;;     "(defun x ())"
 ;;     'emacs-lisp-mode
 ;;     '(2 8)
 ;;     '(font-lock-keyword-face font-lock-function-name-face))
+;; #+end_src
+
+;; It is also possible to define locations with regexps; again either one or
+;; multiple regexps can be used. With a single string, all matches are checked,
+;; with the first match to the first is checked, then the next match to the
+;; second, incrementally.
+
+;; #+begin_src elisp
+;;    (sisyphus-face-at=
+;;     "(defun x ())\n(defun y ())\n(defun z ())"
+;;     'emacs-lisp-mode
+;;     "defun"
+;;     'font-lock-keyword-face)
+
+;;    (sisyphus-face-at=
+;;     "(defun x ())\n(defmacro y ())\n(defun z ())"
+;;     'emacs-lisp-mode
+;;     '("defun" "defmacro" "defun")
+;;     'font-lock-keyword-face)
+;; #+end_src
 
 
+;; The locations can also be specified as a `lambda' which takes a single
+;; argument of a buffer. The return result can be any form of location accepted
+;; by `sisyphus-face-at=', including a list of match data generated, as in this
+;; case, by the `m-buffer' package.
+
+;; #+begin_src elisp
 ;;    (sisyphus-face-at=
 ;;     "(defun x ())\n(defun y ())\n(defun z ())"
 ;;     'emacs-lisp-mode
@@ -826,6 +865,11 @@ the copy of FILE will be in a different directory."
 ;; #+end_src
 
 
+;; *** Implementation
+
+;; First, `sisyphus-face-at='.
+
+
 ;; #+begin_src emacs-lisp
 (defun sisyphus--face-at-location=
     (location face property throw-on-nil)
@@ -974,7 +1018,11 @@ operates over files and takes the mode from that file."
 (put 'sisyphus-face-at=
      'ert-explainer
      'sisyphus-explain-face-at=)
+;; #+end_src
+
+;; Followed by `sisyphus-file-face-at='.
 
+;; #+begin_src emacs-lisp
 (defun sisyphus--file-face-at=-1 (file locations faces property throw-on-nil)
   (sisyphus-with-find-file
       (sisyphus-make-related-file file)