[DOC] owl: add generic file level documentation

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
 //------------------------------------------------------------------------------

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.
  */
 
 //------------------------------------------------------------------------------

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";

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;

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[] = [];

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
 //------------------------------------------------------------------------------

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
 //------------------------------------------------------------------------------

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
 //------------------------------------------------------------------------------

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 "";

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 {