Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'doc/client.texi')
-rw-r--r--doc/client.texi98
1 files changed, 98 insertions, 0 deletions
diff --git a/doc/client.texi b/doc/client.texi
new file mode 100644
index 0000000..8955264
--- /dev/null
+++ b/doc/client.texi
@@ -0,0 +1,98 @@
+@c This document is part of the Liza Data Collection Framework manual.
+@c Copyright (C) 2017 R-T Specialty, LLC.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts. A copy of the license is included in the section entitled ``GNU
+@c Free Documentation License''.
+
+@node Client
+@chapter Client
+@maintstart
+@footnote{
+ The client is largely managed by a single class,
+ @srcref{src/client/Client.js, Client},
+ which has grown out of control.
+ @code{Client} mediates essentially the entire system.
+ Code is to be extracted out of this class as it is touched.
+
+ The other system mammoth is @code{Ui} (@pxref{Program UI}).}
+@maintend
+
+@helpwanted
+
+@menu
+* Error Handling::
+@end menu
+
+
+@node Error Handling
+@section Error Handling
+
+@maintenance{
+ The complexity of this system and integration into legacy
+ layers has caused maintenance trouble in the past.
+ Each of the error checking layers need to be integrated
+ to reduce complexity.}
+
+@cindex Error
+@cindex Failure
+There are three layers of error checking:@footnote{
+ Primarily for legacy reasons.
+ They are being consolodated as the system is touched.}
+
+@enumerate
+ @item Required field checking@mdash{
+ }whether all required questions have been answered.
+ @item Type Validation@mdash{
+ }verify that questions contain valid data according to their
+ declared type. @ref{Validation}.
+ @item Assertions@mdash{
+ }arbitrary checks on data.
+ @ref{Assertions}.
+@end enumerate
+
+@cindex Required Field
+@cindex Field, Required
+@cindex Field, Fixed
+@cindex Error, Fixed
+@cindex Error, Required
+@cindex Fixed, Error
+Required fields fail serially@mdash{
+ }the system will notify the user of the required field,
+ and direct him/her to it (usually through scrolling).
+A field is marked as @dfn{fixed} according to the rules
+ in @ref{Managing Error State}.
+
+
+@menu
+* Managing Error State:: Determining when failures should be marked as ``fixed''
+@end menu
+
+
+@node Managing Error State
+@subsection Managing Error State
+
+@cindex Failure Stack
+@cindex Error Stack
+Each failure caused by assertions is associated with a
+ @dfn{failure stack}.
+The stack represents the trail of assertions that have run,
+ containing the ids of all values asserted against.
+When any field or classification changes that is represented on the
+ failure stack,
+ the failure for the failed field associated with that failure stack
+ is cleared.
+
+@exnotice{
+ If an assertion for some question @var{foo} first checked the value
+ of bucket field @var{bar},
+ and within its failure checked the value @var{c:predicate},
+ the failure stack would contain both of those ids.
+ If either @var{bar} or the @var{predicate} classification changed,
+ the question @var{foo} would have its error cleared.}
+
+Error state is managed by
+ @srcref{src/validate/ValidStateMonitor.js, ValidStateMonitor}.