Bug 928195 - Part 6: Add docs for WebIDL and the build system; r=froydnj

--HG--
extra : rebase_source : cee29c0bf5c050d73ef02d6ad933802b8fad21e0

dom/bindings/docs/index.rst

@@ -0,0 +1,122 @@
+.. _webidl:
+
+======
+WebIDL
+======
+
+WebIDL describes interfaces web browsers are supposed to implement.
+
+The interaction between WebIDL and the build system is somewhat complex.
+This document will attempt to explain how it all works.
+
+Overview
+========
+
+``.webidl`` files throughout the tree define interfaces the browser
+implements. Since Gecko/Firefox is implemented in C++, there is a
+mechanism to convert these interfaces and associated metadata to
+C++ code. That's where the build system comes into play.
+
+All the code for interacting with ``.webidl`` files lives under
+``dom/bindings``. There is code in the build system to deal with
+WebIDLs explicitly.
+
+WebIDL source file flavors
+==========================
+
+Not all ``.webidl`` files are created equal! There are several flavors,
+each represented by a separate symbol from :ref:`mozbuild_symbols`.
+
+WEBIDL_FILES
+   Refers to regular/static ``.webidl`` files. Most WebIDL interfaces
+   are defined this way.
+
+GENERATED_EVENTS_WEBIDL_FILES
+   In addition to generating a binding, these ``.webidl`` files also
+   generate a source file implementing the event object in C++
+
+PREPROCESSED_WEBIDL_FILES
+   The ``.webidl`` files are generated by preprocessing an input file.
+   They otherwise behave like *WEBIDL_FILES*.
+
+TEST_WEBIDL_FILES
+   Like *WEBIDL_FILES* but the interfaces are for testing only and
+   aren't shipped with the browser.
+
+PREPROCESSED_TEST_WEBIDL_FILES
+   Like *TEST_WEBIDL_FILES* except the ``.webidl`` is obtained via
+   preprocessing, much like *PREPROCESSED_WEBIDL_FILES*.
+
+GENERATED_WEBIDL_FILES
+   The ``.webidl`` for these is obtained through an *external*
+   mechanism. Typically there are custom build rules for producing these
+   files.
+
+Producing C++ code
+==================
+
+The most complicated part about WebIDLs is the process by which
+``.webidl`` files are converted into C++.
+
+This process is handled by code in the :py:mod:`mozwebidlcodegen`
+package. :py:class:`mozwebidlcodegen.WebIDLCodegenManager` is
+specifically where you want to look for how code generation is
+performed. This includes complex dependency management.
+
+Requirements
+============
+
+This section aims to document the build and developer workflow requirements
+for WebIDL.
+
+Parser unit tests
+   There are parser tests provided by ``dom/bindings/parser/runtests.py``
+   that should run as part of ``make check``. There must be a mechanism
+   to run the tests in *human* mode so they output friendly error
+   messages.
+
+   The current mechanism for this is ``mach webidl-parser-test``.
+
+Mochitests
+   There are various mochitests under ``dom/bindings/test``. They should
+   be runnable through the standard mechanisms.
+
+Working with test interfaces
+   ``TestExampleGenBinding.cpp`` calls into methods from the
+   ``TestExampleInterface`` and ``TestExampleProxyInterface`` interfaces.
+   These interfaces need to be generated as part of the build. These
+   interfaces should not be exported or packaged.
+
+   There is a ``compiletests`` make target in ``dom/bindings`` that
+   isn't part of the build that facilitates turnkey code generation
+   and test file compilation.
+
+Minimal rebuilds
+   Reprocessing every output for every change is expensive. So we don't
+   inconvenience people changing ``.webidl`` files, the build system
+   should only perform a minimal rebuild when sources change.
+
+   This logic is mostly all handled in
+   :py:class:`mozwebidlcodegen.WebIDLCodegenManager`. The unit tests for
+   that Python code should adequately test typical rebuild scenarios.
+
+   Bug 940469 tracks making the existing implementation better.
+
+Explicit method for performing codegen
+   There needs to be an explicit method for invoking code generation.
+   It needs to cover regular and test files.
+
+   This is implemented via ``make export`` in ``dom/bindings``.
+
+No-op binding generation should be fast
+   So developers touching ``.webidl`` files are not inconvenienced,
+   no-op binding generation should be fast. Watch out for the build system
+   processing large dependency files it doesn't need in order to perform
+   code generation.
+
+Ability to generate example files
+   *Any* interface can have example ``.h``/``.cpp`` files generated.
+   There must be a mechanism to facilitate this.
+
+   This is currently facilitated through ``mach webidl-example``. e.g.
+   ``mach webidl-example HTMLStyleElement``.

dom/bindings/moz.build

@@ -87,3 +87,6 @@ if CONFIG['MOZ_AUDIO_CHANNEL_MANAGER']:
     ]
 
 FINAL_LIBRARY = 'xul'
+
+SPHINX_TREES['webidl'] = 'docs'
+SPHINX_PYTHON_PACKAGE_DIRS += ['mozwebidlcodegen']