From 45200baedd01dad3f288d1be1dbd6d476c258396 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Mon, 23 Mar 2015 15:11:35 -0400 Subject: [PATCH] `base' package documentation --- core/base.xml | 208 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 154 insertions(+), 54 deletions(-) diff --git a/core/base.xml b/core/base.xml index 727d6205..84001eac 100644 --- a/core/base.xml +++ b/core/base.xml @@ -1,4 +1,4 @@ - + + xmlns:c="http://www.lovullo.com/calc" + core="true" + desc="Base features"> + + The \pkgself~package exposes common and internal + defintions. Ideally, this package will be included automatically by + the compiler to remove repetitive, boilerplate imports. Importing + this package isn't necessary if none of these definitions are + needed. - - - - - +
+ \ref{_CMATCH_} is a magic constant that contains the result of + a~classification match. This is used implicity by + \ref{rate-each}.\footnote{The symbol is \Xi~because it looks like + a sideways array.} - - + \todo{Remove in favor of a local variable or generated + classification; there is no need (anymore) for this to be magic.} - - + + + - - - + The runtime is responsible for populating \ref{__DATE_YEAR__} with + a proper value representing the current year. - - - - + \todo{TAME is deterministic with this one exception; remove it and + have users use a param instead if they need this datum.} - - - - - - - - - - - + +
- - + +
+ Primitives are defined internally; these definitions simply + provide symbols to permit their use. + + + + - + + + - + + \ref{empty} does not have much use outside of the compiler. + + + + +
+ + + +
+ Negation is a common task and it was tedious in older versions of + TAME\footnote{Before it was even called TAME, actually.} For + these situations, \ref{NEGATE} is provided to avoid having to use + a~\ref{const} expression. + + + + + Similarly, $0$~is a~common value. Where a value is required (such + as a~template argument), \ref{ZERO} may be used. TAME now + supports a~constant-scalar syntax ({\tt #0}; \todo{reference this + in documentation}), making this largely unnecessary. + + This is declared as a float to provide compatibility with all + types of expressions. + + + + + In the case where classifications are required, but a~static + assumption about the applicability of the subject can be made, we + have values that are always~true and always~false. The use + of~\ref{never} may very well be a~code smell, but let us not rush + to judgment.\footnote{\ref{never} has been added as an analog + to~\ref{always}; its author has never had use for it. Oh, look, + we just used ``never''.} + + + + +
+ + + +
+ The templates in this section handle code that is + a~work-in-progress; they should probably not be used in production + code, since they indicate that something is incomplete or unused. + + \ref{_todo_} formalizes TODO items and \may~always yield a scalar + integer~0, so it may be used within calculations. If yielding a + constant value is not appropriate, it \may~also be stripped from + the output entirely. + + + + + The \ref{_ignore_} template serves as a~block + comment.\footnote{This is useful since XML does not support nested + comments, which makes it difficult to comment out code that + already has XML comments.} It may be useful for debugging, but is + discouraged for use otherwise. The \ref{_ignore_/@desc@} param + should be used to describe intent. + + +
+ + + +