From fc53a08bb0ffaf2bd49408f50701f17cdd603fb9 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 24 May 2017 15:46:49 +0200 Subject: [PATCH] add some more docs --- src/checkable.ts | 69 +++++++++++++++++++++++++++++++++++++++++++----- src/cryptoApi.ts | 7 ++++- src/i18n.tsx | 11 ++++++-- 3 files changed, 77 insertions(+), 10 deletions(-) diff --git a/src/checkable.ts b/src/checkable.ts index 8af70f50f..8eb5e1520 100644 --- a/src/checkable.ts +++ b/src/checkable.ts @@ -18,12 +18,23 @@ "use strict"; /** - * Decorators for type-checking JSON into - * an object. - * @module Checkable - * @author Florian Dold + * Decorators for validating JSON objects and converting them to a typed + * object. + * + * The decorators are put onto classes, and the validation is done + * via a static method that is filled in by the annotation. + * + * Example: + * ``` + * @Checkable.Class + * class Person { + * @Checkable.String + * name: string; + * @Checkable.Number + * age: number; + * } + * ``` */ - export namespace Checkable { type Path = (number | string)[]; @@ -187,6 +198,11 @@ export namespace Checkable { } + /** + * Class with checkable annotations on fields. + * This annotation adds the implementation of the `checked` + * static method. + */ export function Class(target: any) { target.checked = (v: any) => { return checkValue(v, { @@ -198,6 +214,10 @@ export namespace Checkable { return target; } + /** + * A checker for a class (see [[Class]) that allows + * extra properties to exist on the JSON object being validated. + */ export function ClassWithExtra(target: any) { target.checked = (v: any) => { return checkValue(v, { @@ -211,6 +231,11 @@ export namespace Checkable { } + /** + * A validator for a class that can have an additional validate + * method. The validate method is a member method of type `() => void` + * that throws an exception on invalidation errors. + */ export function ClassWithValidator(target: any) { target.checked = (v: any) => { let cv = checkValue(v, { @@ -230,6 +255,9 @@ export namespace Checkable { } + /** + * Target property must be a Checkable object of the given type. + */ export function Value(type: any) { if (!type) { throw Error("Type does not exist yet (wrong order of definitions?)"); @@ -247,6 +275,10 @@ export namespace Checkable { } + /** + * List of values that match the given annotation. For example, `@Checkable.List(Checkable.String)` is + * an annotation for a list of strings. + */ export function List(type: any) { let stub = {}; type(stub, "(list-element)"); @@ -269,6 +301,10 @@ export namespace Checkable { } + /** + * Map from the key type to value type. Takes two annotations, + * one for the key type and one for the value type. + */ export function Map(keyType: any, valueType: any) { let keyStub = {}; keyType(keyStub, "(map-key)"); @@ -296,6 +332,9 @@ export namespace Checkable { } + /** + * Makes another annotation optional, for example `@Checkable.Optional(Checkable.Number)`. + */ export function Optional(type: any) { let stub = {}; type(stub, "(optional-element)"); @@ -319,12 +358,18 @@ export namespace Checkable { } + /** + * Target property must be a number. + */ export function Number(target: Object, propertyKey: string | symbol): void { let chk = getCheckableInfo(target); chk.props.push({ propertyKey: propertyKey, checker: checkNumber }); } + /** + * Target property must be an arbitary object. + */ export function AnyObject(target: Object, propertyKey: string | symbol): void { let chk = getCheckableInfo(target); chk.props.push({ @@ -334,6 +379,12 @@ export namespace Checkable { } + /** + * Target property can be anything. + * + * Not useful by itself, but in combination with higher-order annotations + * such as List or Map. + */ export function Any(target: Object, propertyKey: string | symbol): void { let chk = getCheckableInfo(target); chk.props.push({ @@ -344,15 +395,19 @@ export namespace Checkable { } + /** + * Target property must be a string. + */ export function String(target: Object, propertyKey: string | symbol): void { let chk = getCheckableInfo(target); chk.props.push({ propertyKey: propertyKey, checker: checkString }); } + /** + * Target property must be a boolean value. + */ export function Boolean(target: Object, propertyKey: string | symbol): void { let chk = getCheckableInfo(target); chk.props.push({ propertyKey: propertyKey, checker: checkBoolean }); } - - } diff --git a/src/cryptoApi.ts b/src/cryptoApi.ts index 1c7c1f95d..45efb63e3 100644 --- a/src/cryptoApi.ts +++ b/src/cryptoApi.ts @@ -20,7 +20,9 @@ * @author Florian Dold */ - +/** + * Imports. + */ import { PreCoinRecord, CoinRecord, @@ -38,6 +40,9 @@ import { } from "./wallet"; +/** + * State of a crypto worker. + */ interface WorkerState { /** * The actual worker thread. diff --git a/src/i18n.tsx b/src/i18n.tsx index 656bb3a05..48631afb2 100644 --- a/src/i18n.tsx +++ b/src/i18n.tsx @@ -18,6 +18,9 @@ * Translation helpers for React components and template literals. */ +/** + * Imports. + */ import * as jedLib from "jed"; import {strings} from "./i18n/strings"; import * as React from "react"; @@ -102,9 +105,11 @@ interface TranslateProps { * in a another non-text element. * * Example: + * ``` * * Hello. Your score is * + * ``` */ export class Translate extends React.Component { render(): JSX.Element { @@ -143,10 +148,12 @@ export class Translate extends React.Component { * Should only contain TranslateSingular and TransplatePlural as children. * * Example: + * ``` * * I have {n} apple. * I have {n} apples. * + * ``` */ export class TranslateSwitch extends React.Component{ render(): JSX.Element { @@ -181,7 +188,7 @@ interface TranslationPluralProps { } /** - * @see TranslateSwitch + * See [[TranslateSwitch]]. */ export class TranslatePlural extends React.Component { render(): JSX.Element { @@ -213,7 +220,7 @@ export class TranslatePlural extends React.Component { render(): JSX.Element {