docs(site): Add index documentation page #48

korzio · Oct 9, 2017 · cb4db59 · cb4db59
1 parent 5e0e1a9
commit cb4db59
Show file tree

Hide file tree

Showing 4 changed files with 186 additions and 83 deletions.
diff --git a/README.md b/README.md
@@ -3,26 +3,18 @@
 
 # djv <a name="title"></a>
 
-Dynamic JSON Schema Validator
+Dynamic JSON-Schema Validator
 
-Current package supports **JSON Schema v6 and v4**. It contains utils to validate objects against schemas.
+Current package supports **JSON-Schema v6 and v4**. It contains utils to validate objects against schemas.
 This is a part of **djv** packages aimed to work with json-schema.
 
 - [djv](https://github.com/korzio/djv) validate object against schemas
 - [djvi](https://github.com/korzio/djvi) instantiate objects by schema definition
 - [jvu](https://github.com/korzio/jvu) utilities for declarative, FP usage
+- [@djv/draft-04](https://github.com/korzio/@djv/draft-04) TODO
 
-Any contributions are welcome. Check [contribution guide](./CONTRIBUTING.md).
-
-**New!!!**
-
-Since version *1.2.0* `djv` package supports `draft-06`.
-The default version is still *draft-04* for the backward compatibility and due to the semantic versioning.
-For `draft-06` use a *version* option in [constructor](#constructor) arguments.
-
-```javascript
-const env = new djv({ version: 'draft-06' });
-```
+Any contributions are welcome. Check the [contribution guide](./CONTRIBUTING.md).
+Since version **1.2.0** *djv* package supports `draft-06`. Version **2.0.0** makes `draft-06` the default schema version. To use other versions check the [environment section](#environment).
 
 ## Table of contents <a name="content"></a>
 
@@ -33,14 +25,14 @@ const env = new djv({ version: 'draft-06' });
 * [API](#api)
   * [Environment](#environment)
   * [addSchema](#addSchema)
-  * [addSchema](#addSchema)
   * [validate](#validate)
   * [removeSchema](#removeSchema)
   * [resolve](#resolve)
   * [export](#export)
   * [import](#import)
   * [addFormat](#addFormat)
   * [setErrorHandler](#errorHandler)
+  * [useVersion](#useVersion)
 * [Tests](#tests)
 * [References](#references)
 
@@ -78,7 +70,7 @@ const jsonSchema = {
     }
 };
 
-// Use `addSchema` to add json schema
+// Use `addSchema` to add json-schema
 env.addSchema('test', jsonSchema);
 env.validate('test#/common', { type: 'common' });
 // => undefined
@@ -91,17 +83,24 @@ env.validate('test#/common', { type: 'custom' });
 
 ### Environment <a name="environment"></a>
 
-To instantiate `djv` environment
+To instantiate *djv* environment
 
 ```javascript
 const djv = require('djv');
 const env = djv({
-  version: 'draft-06', // use json-schema draft-06
+  version: 'draft-04', // use json-schema draft-06
   formats: { /*...*/ }, // custom formats @see #addFormat
   errorHandler: () => { /*...*/ }, // custom error handler, @see #setErrorHandler
 });
 ```
 
+To use a previous version of JSON-Schema draft, use a [`draft-04` plugin](https://www.npmjs.com/package/@korzio/djv-draft-04), specified in [*optionalDependencies*](https://docs.npmjs.com/files/package.json#optionaldependencies) of *djv* package.
+
+```javascript
+const env = new djv({ version: 'draft-04' });
+```
+
+
 ### addSchema(name: string, schema: object?) -> resolved: object <a name="addSchema"></a>
 
 Add a schema to a current djv environment,
@@ -208,79 +207,38 @@ djv({
 When a custom error handler is used, the template body function adds a `error` variable inside a generated validator, which can be used to put error information. `errorType` is always passed to error handler function. Some validate utilities put extra argument, like f.e. currently processed property value. Inside the handler context is a templater instance, which contains `this.schema`, `this.data` paths arrays to identify validator position.
 @see test/index/setErrorHandler for more examples
 
+### useVersion(version: string, configure: function) <a name="useVersion"></a>
 
-## Tests <a name="tests"></a>
+To customize environment provide a `configure` function which will update configuration for *djv* instance.
 
+```javascript
+env.useVersion('draft-04')
+// or
+env.useVersion('custom', configure)
 ```
-npm test
-```
-
-## References <a name="references"></a>
-
-* [JSON-Schema Specification](http://json-schema.org/)
-* [JSON Schema Benchmark](https://github.com/ebdrup/json-schema-benchmark)
-
-<!---
-
-## What relative tasks can be? Why use json-schema?
-
-### Meta programming
 
-What is [generate-function](https://www.npmjs.com/package/generate-function)? How to write well-optimized functions?
+`Configure` will get internal properties as an argument. Check the [@korzio/djv-draft-04 code](https://github.com/korzio/-djv-draft-04/blob/master/index.js).
 
-- Templates
-- Validators
-
-### Goals
-
-- keep structure and code clean
-
-in is-my-json-schema-valid and jjv packages structure is - one file
-
-- add architecture ability to set instantiate and randomize data
-- fast validation
-- normal speed generation
-
-### Refactoring jjv
-
-- splitted into files
-- updated variable names
-
-### Refactoring for generated function
-
-investigate c++ inline functions
-
-- is-my-json-valid implementation
-- got a generated-function
-- updated generated function with few methods - resolve, error, etc, cache - Maybe it is better to use some meta language for it?
-
-### Optimized things
-
-- Added Measured
-- Describe All measurements
-
-### Google Closure Advanced
-
-- features
-- what is used
-- why still need optimizations
-
-## TODO
+```javascript
+exposed = {
+  properties,
+  keywords,
+  validators,
+  formats,
+  keys,
+  transformation,
+}
+```
 
-### Todo Optimizations List
+**!Important** Modifing them will affect all *djv* instances in an application.
 
-- generatedNonReffunctions 1377, generatedfunctionsUsed 3003 - make fn.if function, and transport scope/context/state to generate function
-- update ref usage for non-ref inline functions - if a linke does not contain refs inside (can be easily checked by json.stringify), it should be a regular if-else consequence as well - Optimize small schemas (like in allOf example - don't generate function, althought return context)
-- [if optimization](http://jsperf.com/ifs-vs-expression)?
-- [killing optimization](http://habrahabr.ru/company/mailru/blog/273839/)
+## Tests <a name="tests"></a>
 
-### General
+```
+npm test
+```
 
-- [asmjs compile step](http://ejohn.org/blog/asmjs-javascript-compile-target/)
-- [compile with google closure or smth](https://www.npmjs.com/package/google-closure-compiler)
-- $data
-- add posibility to customize validators
-- add nested tests
-- add tests to [resolve](http://tools.ietf.org/html/draft-zyp-json-schema-04#section-7.2.4)
+## References <a name="references"></a>
 
--->
+* [JSON-Schema Specification](http://json-schema.org/)
+* [JSON-Schema Benchmark](https://github.com/ebdrup/json-schema-benchmark)
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,18 @@
+# DJV Documents
+
+Dynamic JSON-Schema Validator documents.
+
+This document contains links to documentation pages.
+
+## General Information
+
+* [Readme](/README.md) - How to use DJV
+* [Release Notes](/docs/release-notes.md) - Manually created release notes
+* [Changelog](/CHANGELOG.md) - An auto-generated changelog from commits messages
+* [Contributing](/CONTRIBUTING.md) - Welcome
+* [License](/LICENSE) - MIT
+
+## Technical Documentation
+
+* [State](/docs/state.md) - The document describes how the state is implemented in *djv* library, explains how schemas are resolved.
+* [Const](/docs/const.md) - A small note on how `const` keyword was implemented.
diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -0,0 +1,63 @@
+# Release Notes <a name="title"></a>
+
+This document contains all notes about the past djv releases.
+Announcements are also sent to [the gitter channel](https://gitter.im/korzio/djv).
+
+[![Join the chat at https://gitter.im/korzio/djv](https://badges.gitter.im/korzio/djv.svg)]
+
+## Table of contents <a name="content"></a>
+
+* [Release Notes](#title)
+* [Table of contents](#content)
+* [2.0.0](#2.0.0)
+* [1.2.0](#1.2.0) - 2017-09-27
+* [1.2.0](#1.1.1) - 2017-07-20
+* [1.0.0](#1.0.0) - 2017-06-17
+
+## 2.0.0 <a name="2.0.0"></a>
+
+Supports **draft-06** by default.
+
+All *draft-04* specific code is removed from the codebase. Within the release a separate library [is published](https://www.npmjs.com/package/@korzio/djv-draft-04) to support *draft-04*. It is installed by default as an [optional dependency](https://docs.npmjs.com/files/package.json#optionaldependencies) for *djv* package.
+
+To specify *draft-04* usage instantiate
+
+```javascript
+const env = djv({
+  version: 'draft-04',
+});
+// or
+djv.useVersion('draft-04')
+```
+
+**!Important** Applying the *draft-04* configuration will affect all *djv* instances in an application. Check the [documentation](/README.md#useVersion).
+
+## 1.2.0 (2017-09-27) <a name="1.2.0"></a>
+
+A [MR](https://github.com/korzio/djv/pull/50) which replaces the previous one and contains 2 big features:
+1. State refactoring - now tests are passing, the algorithm is redesigned (however there are still things to do in future)
+2. Draft-06 implemented
+
+Supports *draft-04* by default and can be configured to validate instances against *draft-06* specification.
+
+## 1.1.1 <a name="1.1.1"></a>
+
+[The release story](https://github.com/korzio/djv/issues/35)
+[The changelog](https://github.com/korzio/djv/blob/master/CHANGELOG.md#111-2017-07-20)
+
+In short - this release was about fixing [the major part of bugs](https://github.com/korzio/djv/issues/35#issuecomment-316698036) of updated json schema benchmark.
+The most of the work was done related to state management. I've tried to refactor that functionality. However the most tests regarding references are passing , there are still a few (5) of them failing. Next release will be about v5/v6 support, and the one after will be state refactoring again - I hope to rewrite it in a "wise" way, with algorithm description, tests analytics, etc.
+The other part was in updating the documentation, so I've created a [document](https://github.com/korzio/djv/blob/master/CONTRIBUTING.md) with a few guides how-to debug and release the package. It will be updated in future.
+
+Great thanks for all comments and participation.
+
+## 1.1.0 <a name="1.1.0"></a>
+
+The release contains
+- 2 features of a custom error format and adding formatters into environment
+- a big refactoring of utils and cleaning the structure
+- a few bug fixes (with a huge improvement of pending internals schemas)
+
+Here is the log for release - https://github.com/korzio/djv/issues/26
+Changelog - https://github.com/korzio/djv/blob/master/CHANGELOG.md
+Great thanks for all comments and participants.
diff --git a/docs/todo.md b/docs/todo.md
@@ -0,0 +1,64 @@
+<!---
+
+## What relative tasks can be? Why use json-schema?
+
+### Meta programming
+
+What is [generate-function](https://www.npmjs.com/package/generate-function)? How to write well-optimized functions?
+
+- Templates
+- Validators
+
+### Goals
+
+- keep structure and code clean
+
+in is-my-json-schema-valid and jjv packages structure is - one file
+
+- add architecture ability to set instantiate and randomize data
+- fast validation
+- normal speed generation
+
+### Refactoring jjv
+
+- splitted into files
+- updated variable names
+
+### Refactoring for generated function
+
+investigate c++ inline functions
+
+- is-my-json-valid implementation
+- got a generated-function
+- updated generated function with few methods - resolve, error, etc, cache - Maybe it is better to use some meta language for it?
+
+### Optimized things
+
+- Added Measured
+- Describe All measurements
+
+### Google Closure Advanced
+
+- features
+- what is used
+- why still need optimizations
+
+## TODO
+
+### Todo Optimizations List
+
+- generatedNonReffunctions 1377, generatedfunctionsUsed 3003 - make fn.if function, and transport scope/context/state to generate function
+- update ref usage for non-ref inline functions - if a linke does not contain refs inside (can be easily checked by json.stringify), it should be a regular if-else consequence as well - Optimize small schemas (like in allOf example - don't generate function, althought return context)
+- [if optimization](http://jsperf.com/ifs-vs-expression)?
+- [killing optimization](http://habrahabr.ru/company/mailru/blog/273839/)
+
+### General
+
+- [asmjs compile step](http://ejohn.org/blog/asmjs-javascript-compile-target/)
+- [compile with google closure or smth](https://www.npmjs.com/package/google-closure-compiler)
+- $data
+- add posibility to customize validators
+- add nested tests
+- add tests to [resolve](http://tools.ietf.org/html/draft-zyp-json-schema-04#section-7.2.4)
+
+-->