From f7f8c34e1cb08109795668fa0d62320a9eeceffd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= <ged@odoo.com>
Date: Wed, 8 May 2019 11:23:48 +0200
Subject: [PATCH] [DOC] owl: add generic file level documentation

---
 src/component.ts       | 11 +++++++++++
 src/event_bus.ts       |  3 ++-
 src/index.ts           |  8 ++++++++
 src/observer.ts        | 25 +++++++++++++++++++++++--
 src/qweb_core.ts       | 20 ++++++++++++++++++--
 src/qweb_directives.ts | 15 +++++++++++++++
 src/qweb_extensions.ts | 12 ++++++++++++
 src/store.ts           | 15 +++++++++++++++
 src/utils.ts           | 16 ++++++++++++++++
 src/vdom.ts            | 17 +++++++++++++++++
 10 files changed, 137 insertions(+), 5 deletions(-)

diff --git a/src/component.ts b/src/component.ts
index a5c2be24..f318c940 100644
--- a/src/component.ts
+++ b/src/component.ts
@@ -3,6 +3,17 @@ import { Observer } from "./observer";
 import { QWeb, CompiledTemplate } from "./qweb_core";
 import { h, patch, VNode } from "./vdom";
 
+/**
+ * Owl Component System
+ *
+ * This file introduces a declarative and composable component system. It
+ * contains:
+ *
+ * - the Env interface (generic type for the environment)
+ * - the Meta interface (the owl specific metadata attached to a component)
+ * - the Component class
+ */
+
 //------------------------------------------------------------------------------
 // Types/helpers
 //------------------------------------------------------------------------------
diff --git a/src/event_bus.ts b/src/event_bus.ts
index 9fe6cfe2..720b9337 100644
--- a/src/event_bus.ts
+++ b/src/event_bus.ts
@@ -3,7 +3,8 @@
  * - emit events
  * - add/remove listeners.
  *
- * This is a useful pattern of communication in some cases.
+ * This is a useful pattern of communication in many cases.  For OWL, each
+ * components and stores are event buses.
  */
 
 //------------------------------------------------------------------------------
diff --git a/src/index.ts b/src/index.ts
index 66be5bb4..1353d133 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,7 +1,15 @@
+/**
+ * This file is the main file packaged by rollup (see rollup.config.js).  From
+ * this file, we export all public owl elements.
+ *
+ * Note that dynamic values, such as a date or a commit hash are added by rollup
+ */
 export { Component } from "./component";
 export { EventBus } from "./event_bus";
 export { Observer } from "./observer";
 
+// we need to import manually the extra directives so they can register
+// themselves in QWeb, otherwise these files will not even be loaded.
 import "./qweb_directives";
 import "./qweb_extensions";
 export { QWeb } from "./qweb_core";
diff --git a/src/observer.ts b/src/observer.ts
index 7281f3f8..a2e2b69f 100644
--- a/src/observer.ts
+++ b/src/observer.ts
@@ -1,7 +1,26 @@
+/**
+ * Owl Observer
+ *
+ * This code contains the logic that allows Owl to observe and react to state
+ * changes.
+ *
+ * This is a Observer class that can observe any JS values.  The way it works
+ * can be summarized thusly:
+ * - primitive values are not observed at all
+ * - Objects are observed by replacing all their keys with getters/setters
+ *   (recursively)
+ * - Arrays are observed by replacing their prototype with a customized version,
+ *   which wrap some methods to allow the tracking of each state change.
+ *
+ * Note that this code is inspired by Vue.
+ */
+
 //------------------------------------------------------------------------------
-// Observer
+// Modified Array prototype
 //------------------------------------------------------------------------------
 
+// we define here a new modified Array prototype, which basically override all
+// Array methods that change some state to be able to track their changes
 const methodsToPatch = [
   "push",
   "pop",
@@ -11,7 +30,6 @@ const methodsToPatch = [
   "sort",
   "reverse"
 ];
-
 const ArrayProto = Array.prototype;
 const ModifiedArrayProto = Object.create(ArrayProto);
 
@@ -46,6 +64,9 @@ for (let method of methodsToPatch) {
   };
 }
 
+//------------------------------------------------------------------------------
+// Observer
+//------------------------------------------------------------------------------
 export class Observer {
   rev: number = 1;
   allowMutations: boolean = true;
diff --git a/src/qweb_core.ts b/src/qweb_core.ts
index 9c54bdf6..334a8dca 100644
--- a/src/qweb_core.ts
+++ b/src/qweb_core.ts
@@ -1,10 +1,27 @@
 import { VNode, h } from "./vdom";
 import { parseXML } from "./utils";
 
+/**
+ * Owl QWeb Engine
+ *
+ * In this file, you will find a QWeb engine/template compiler.  It is the core
+ * of how Owl component works.
+ *
+ * Briefly, Owl QWeb compiles XML templates into functions that output a virtual
+ * DOM representation.
+ *
+ * We have here:
+ * - a CompilationContext class, which is an internal object that contains all
+ *   compilation specific information, while a template is being compiled.
+ * - a QWeb class: this is the code of the QWeb compiler.
+ *
+ * Note that this file does not contain the implementation of the QWeb
+ * directives (see qweb_directives.ts and qweb_extensions.ts).
+ */
+
 //------------------------------------------------------------------------------
 // Types
 //------------------------------------------------------------------------------
-
 export type EvalContext = { [key: string]: any };
 export type CompiledTemplate = (context: EvalContext, extra: any) => VNode;
 
@@ -86,7 +103,6 @@ export const UTILS = {
 //------------------------------------------------------------------------------
 // Compilation Context
 //------------------------------------------------------------------------------
-
 export class Context {
   nextID: number = 1;
   code: string[] = [];
diff --git a/src/qweb_directives.ts b/src/qweb_directives.ts
index 16272af9..19518273 100644
--- a/src/qweb_directives.ts
+++ b/src/qweb_directives.ts
@@ -1,5 +1,20 @@
 import { Context, QWeb, UTILS } from "./qweb_core";
 
+/**
+ * Owl QWeb Directives
+ *
+ * This file contains the implementation of most standard QWeb directives:
+ * - t-esc
+ * - t-raw
+ * - t-set/t-value
+ * - t-if/t-elif/t-else
+ * - t-call
+ * - t-foreach/t-as
+ * - t-debug
+ * - t-log
+ */
+
+
 //------------------------------------------------------------------------------
 // t-esc and t-raw
 //------------------------------------------------------------------------------
diff --git a/src/qweb_extensions.ts b/src/qweb_extensions.ts
index 1a5085f8..8d52a86c 100644
--- a/src/qweb_extensions.ts
+++ b/src/qweb_extensions.ts
@@ -1,5 +1,17 @@
 import { QWeb, UTILS } from "./qweb_core";
 
+/**
+ * Owl QWeb Extensions
+ *
+ * This file contains the implementation of non standard QWeb directives, added
+ * by Owl and that will only work on Owl projects:
+ *
+ * - t-on
+ * - t-ref
+ * - t-transition
+ * - t-widget/t-props/t-keepalive
+ */
+
 //------------------------------------------------------------------------------
 // t-on
 //------------------------------------------------------------------------------
diff --git a/src/store.ts b/src/store.ts
index 7f187d98..e92ac0be 100644
--- a/src/store.ts
+++ b/src/store.ts
@@ -2,6 +2,21 @@ import { Component, Env } from "./component";
 import { EventBus } from "./event_bus";
 import { Observer } from "./observer";
 
+/**
+ * Owl Store
+ *
+ * We have here:
+ * - a Store class
+ * - a connect function
+ *
+ * The Owl store is our answer to the problem of managing complex state across
+ * components. The main idea is that the store owns some state, allow external
+ * code to modify it through actions/mutations, and for each state changes,
+ * connected component will be notified, and updated if necessary.
+ *
+ * Note that this code is partly inspired by VueX and React/Redux
+ */
+
 //------------------------------------------------------------------------------
 // Store Definition
 //------------------------------------------------------------------------------
diff --git a/src/utils.ts b/src/utils.ts
index fe1cc7e2..2a44994a 100644
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -1,3 +1,19 @@
+/**
+ * Owl Utils
+ *
+ * We have here a small collection of utility functions:
+ *
+ * - escape
+ * - memoize
+ * - debounce
+ * - patch
+ * - unpatch
+ * - loadTemplates
+ * - loadJS
+ * - whenReady
+ * - parseXML
+ */
+
 export function escape(str: string | number | undefined): string {
   if (str === undefined) {
     return "";
diff --git a/src/vdom.ts b/src/vdom.ts
index 661b7caa..a00ca645 100644
--- a/src/vdom.ts
+++ b/src/vdom.ts
@@ -1,3 +1,20 @@
+/**
+ * Owl VDOM
+ *
+ * This file contains an implementation of a virtual DOM, which is a system that
+ * can generate in-memory representations of a DOM tree, compare them, and
+ * eventually change a concrete DOM tree to match its representation, in an
+ * hopefully efficient way.
+ *
+ * Note that this code is a fork of Snabbdom, slightly tweaked/optimized for our
+ * needs (see https://github.com/snabbdom/snabbdom).
+ *
+ * The main exported values are:
+ * - interface VNode
+ * - h function (a helper function to generate a vnode)
+ * - patch function (to apply a vnode to an actual DOM node)
+ */
+
 
 // because those in TypeScript are too restrictive: https://github.com/Microsoft/TSJS-lib-generator/pull/237
 declare global {