Mojo: Update/add README.md files.

Also move async_waiter.h from c/system to c/environment. (It's not a
part of the system API per se; instead, it defines stuff that the app
must provide to, e.g., the gles2 subsystem. This move makes the
organization of the C subdirectory more closely parallel the C++
subdirectory.)

R=darin@chromium.org

Review URL: https://codereview.chromium.org/244883005

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@265176 0039d316-1c4b-4281-b951-d872f2087c98

13 files changed, 159 insertions, 57 deletions

diff --git a/mojo/bindings/js/waiting_callback.h b/mojo/bindings/js/waiting_callback.h
index bc17d19..90cf284 100644
--- a/mojo/bindings/js/waiting_callback.h
+++ b/mojo/bindings/js/waiting_callback.h
@@ -8,7 +8,7 @@
 #include "gin/handle.h"
 #include "gin/runner.h"
 #include "gin/wrappable.h"
-#include "mojo/public/c/system/async_waiter.h"
+#include "mojo/public/c/environment/async_waiter.h"
 
 namespace mojo {
 namespace js {
diff --git a/mojo/environment/default_async_waiter_impl.h b/mojo/environment/default_async_waiter_impl.h
index 266a70f6..8e697cb 100644
--- a/mojo/environment/default_async_waiter_impl.h
+++ b/mojo/environment/default_async_waiter_impl.h
@@ -6,7 +6,7 @@
 #define MOJO_ENVIRONMENT_DEFAULT_ASYNC_WAITER_IMPL_H_
 
 #include "mojo/environment/mojo_environment_impl_export.h"
-#include "mojo/public/c/system/async_waiter.h"
+#include "mojo/public/c/environment/async_waiter.h"
 
 namespace mojo {
 namespace internal {
diff --git a/mojo/mojo_public.gypi b/mojo/mojo_public.gypi
index 9defef5..b4b1942 100644
--- a/mojo/mojo_public.gypi
+++ b/mojo/mojo_public.gypi
@@ -26,7 +26,6 @@
         ],
       },
       'sources': [
-        'public/c/system/async_waiter.h',
         'public/c/system/core.h',
         'public/c/system/macros.h',
         'public/c/system/system_export.h',
diff --git a/mojo/public/README.md b/mojo/public/README.md
index 32fc4b1..a31a8a8 100644
--- a/mojo/public/README.md
+++ b/mojo/public/README.md
@@ -1,62 +1,43 @@
 Mojo Public API
 ===============
 
-The Mojo Public API is a binary stable API to the Mojo system. There are
-several components to the API:
+The Mojo Public API is a binary stable API to the Mojo system.
 
-Bindings
---------
-
-This directory contains a static library that clients may link into their
-binary. The contents of this directory are not binary stable as each client is
-free to use whichever version they prefer.
+It consists of support for a number of programming languages (with a directory
+for each support language), some "build" tools and build-time requirements, and
+interface definitions for Mojo services (specified using an IDL).
 
-This directory also contains a compiler that translates mojom interface
-definition files into idiomatic bindings for various languages, including
-C++ and JavaScript. Clients are expected to statically link with the generated
-code, which reads and writes the binary stable IPC message format.
+Note that there are various subdirectories named tests/. These contain tests of
+the code in the enclosing directory, and are not meant for use by Mojo
+applications.
 
-Environment
------------
+C/CPP/JS
+--------
 
-This directory contains a static library that clients may link into their
-binary. The contents of this directory are not binary stable as each client is
-free to use whichever version they prefer.
+The c/, cpp/, js/ subdirectories define the API for C, C++, and JavaScript,
+respectively.
 
-The environment static library represents the shared state that is needed to
-support the Bindings and GLES2 libraries. It depends on the Utility library.
+The basic principle for these directories is that they consist of the source
+files that one needs at build/deployment/run time (as appropriate for the
+language), organized in a natural way for the particular language.
 
-GLES2
------
+Interfaces
+----------
 
-The IPC protocol used to communicate between Mojo client and the GLES2
-service is not binary stable. To insulate themselves from changes in this
-protocol, clients are expected to link dynamically against the standard GLES2
-headers from Khronos and the headers in this directory, which provide an
-adaptor between the GLES2 C API and the underlying IPC protocol.
+The interfaces/ subdirectory contains Mojo IDL (a.k.a. .mojom) descriptions of
+standard Mojo services.
 
-System
-------
+Platform
+--------
 
-This directory defines the interface between Mojo clients and the Mojo IPC
-system. Although the Mojo IPC message format is binary stable, the mechanism
-by which these messages are transported is not stable. To insulate themselves
-from changes in the underlying transport, clients are expected to link against
-these headers dynamically.
+The platform/ subdirectory contains any build-time requirements (e.g., static
+libraries) that may be needed to produce a Mojo application for certain
+platforms, such as a native shared library or as a NaCl binary.
 
-Tests
+Tools
 -----
 
-This directory contains tests for code contained in the public API. Mojo
-clients are expected to ignore this directory.
-
-Utility
--------
-
-This directory contains a static library that clients may link into their
-binary. The contents of this directory are not binary stable as each client is
-free to use whichever version they prefer.
-
-The Utility static library most notably defines an implementation of a RunLoop
-based on the MojoWaitMany that clients may use as the basis for asynchronous
-message processing.
+The tools/ subdirectory contains tools that are useful/necessary at
+build/deployment time. These tools may be needed (as a practical necessity) to
+use the API in any given language, e.g., to generate bindings from Mojo IDL
+files.
diff --git a/mojo/public/c/README.md b/mojo/public/c/README.md
new file mode 100644
index 0000000..8e11545
--- /dev/null
+++ b/mojo/public/c/README.md
@@ -0,0 +1,45 @@
+Mojo Public C API
+=================
+
+This directory contains C language bindings for the Mojo Public API.
+
+Environment
+-----------
+
+The environment/ subdirectory defines some common things that, while not part of
+the system API, may be required for GLES2 (for example). These are things that a
+Mojo application may be required to provide to the GLES2 (for example) library
+in order to use it. (However, the Mojo application may implement these things as
+it sees fit.)
+
+GLES2
+-----
+
+The gles2/ subdirectory defines the GLES2 C API that's available to Mojo
+applications. To use GLES2, Mojo applications must link against a dynamic
+library (the exact mechanism being platform-dependent) and use the header files
+in this directory as well as the standard Khronos GLES2 header files.
+
+The reason for this, rather than providing GLES2 using the standard Mojo IPC
+mechanism, is performance: The protocol (and transport mechanisms) used to
+communicate with the Mojo GLES2 service is not stable nor "public" (mainly for
+performance reasons), and using the dynamic library shields the application from
+changes to the underlying system.
+
+System
+------
+
+The system/ subdirectory provides definitions of the basic low-level API used by
+all Mojo applications (whether directly or indirectly). These consist primarily
+of the IPC primitives used to communicate with Mojo services.
+
+Though the message protocol is stable, the implementation of the transport is
+not, and access to the IPC mechanisms must be via the primitives defined in this
+directory.
+
+Test Support
+------------
+
+This directory contains a C API for running tests. This API is only available
+under special, specific test conditions. It is not meant for general use by Mojo
+applications.
diff --git a/mojo/public/c/system/async_waiter.h b/mojo/public/c/environment/async_waiter.h
index ab999a3..0568954 100644
--- a/mojo/public/c/system/async_waiter.h
+++ b/mojo/public/c/environment/async_waiter.h
@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-#ifndef MOJO_PUBLIC_C_SYSTEM_ASYNC_WAITER_H_
-#define MOJO_PUBLIC_C_SYSTEM_ASYNC_WAITER_H_
+#ifndef MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_
+#define MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_
 
 #include "mojo/public/c/system/core.h"
 
@@ -37,4 +37,4 @@ struct MojoAsyncWaiter {
 }  // extern "C"
 #endif
 
-#endif  // MOJO_PUBLIC_C_SYSTEM_ASYNC_WAITER_H_
+#endif  // MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_
diff --git a/mojo/public/c/gles2/DEPS b/mojo/public/c/gles2/DEPS
new file mode 100644
index 0000000..3887457
--- /dev/null
+++ b/mojo/public/c/gles2/DEPS
@@ -0,0 +1,3 @@
+include_rules = [
+  "+mojo/public/c/environment",
+]
diff --git a/mojo/public/c/gles2/gles2.h b/mojo/public/c/gles2/gles2.h
index 6b20b9c..3ee249d 100644
--- a/mojo/public/c/gles2/gles2.h
+++ b/mojo/public/c/gles2/gles2.h
@@ -10,9 +10,9 @@
 #include <stdint.h>
 #include <GLES2/gl2.h>
 
+#include "mojo/public/c/environment/async_waiter.h"
 #include "mojo/public/c/gles2/gles2_export.h"
 #include "mojo/public/c/gles2/gles2_types.h"
-#include "mojo/public/c/system/async_waiter.h"
 #include "mojo/public/c/system/core.h"
 
 #ifdef __cplusplus
diff --git a/mojo/public/c/system/tests/core_unittest_pure_c.c b/mojo/public/c/system/tests/core_unittest_pure_c.c
index 7293ff2..a95af50 100644
--- a/mojo/public/c/system/tests/core_unittest_pure_c.c
+++ b/mojo/public/c/system/tests/core_unittest_pure_c.c
@@ -11,8 +11,8 @@
 
 // Include all the header files that are meant to be compilable as C. Start with
 // core.h, since it's the most important one.
+#include "mojo/public/c/environment/async_waiter.h"
 #include "mojo/public/c/system/core.h"
-#include "mojo/public/c/system/async_waiter.h"
 #include "mojo/public/c/system/macros.h"
 
 // The joys of the C preprocessor....
diff --git a/mojo/public/cpp/README.md b/mojo/public/cpp/README.md
new file mode 100644
index 0000000..8f03d98
--- /dev/null
+++ b/mojo/public/cpp/README.md
@@ -0,0 +1,71 @@
+Mojo Public C++ API
+===================
+
+This directory contains C++ language bindings for the Mojo Public API.
+
+A number of subdirectories provide wrappers for the lower-level C APIs (in
+subdirectories of the same name, under mojo/public/c/). Typically, these
+wrappers provide increased convenience and/or type-safety.
+
+Other subdirectories provide support (static) libraries of various sorts. In
+this case, the organization is to have the public interface for the library in
+defined in header files in the subdirectory itself and the implementation of the
+library at a lower level, under a lib (sub)subdirectory. A developer should be
+able to substitute their own implementation of any such support library, and
+expect other support libraries, which may depend on that library, to work
+properly.
+
+Bindings
+--------
+
+The bindings/ subdirectory contains a support (static) library needed by the
+code generated by the bindings generator tool (in mojo/public/tools/bindings/),
+which translates Mojo IDL (.mojom) files into idiomatic C++ (among other
+languages).
+
+This library depends on the Environment library.
+
+Environment
+-----------
+
+The environment/ subdirectory contains a support (static) library that
+represents shared state needed to support the Bindings and GLES2 libraries.
+
+This library depends on the Utility library.
+
+
+GLES2
+-----
+
+The gles2/ subdirectory contains C++ wrappers (and some additional helpers) of
+the API defined in mojo/public/c/gles2/ (which provides access to GLES2).
+
+These wrappers depend on the Environment library.
+
+Shell
+-----
+
+The shell/ subdirectory contains a support (static) library that aids in writing
+Mojo applications and interacting with the Shell service.
+
+System
+------
+
+The system/ subdirectory contains C++ wrappers (and some additional helpers) of
+the API defined in mojo/public/c/system/, which defines the basic, "core" API,
+especially used to communicate with Mojo services.
+
+Test Support
+------------
+
+The test_support/ subdirectory contains C++ wrappers of the test-only API
+defined in mojo/public/c/test_support/. It is not meant for general use by Mojo
+applications.
+
+Utility
+-------
+
+The utility/ subdirectory contains a support (static) library that provides
+various basic functionality. Most notably, it provides an implementation of a
+RunLoop based on MojoWaitMany() that applications may use as the basis for
+asynchronous message processing.
diff --git a/mojo/public/cpp/environment/DEPS b/mojo/public/cpp/environment/DEPS
new file mode 100644
index 0000000..3887457
--- /dev/null
+++ b/mojo/public/cpp/environment/DEPS
@@ -0,0 +1,3 @@
+include_rules = [
+  "+mojo/public/c/environment",
+]
diff --git a/mojo/public/cpp/environment/default_async_waiter.h b/mojo/public/cpp/environment/default_async_waiter.h
index d7f48bf..6edfaaa 100644
--- a/mojo/public/cpp/environment/default_async_waiter.h
+++ b/mojo/public/cpp/environment/default_async_waiter.h
@@ -5,7 +5,7 @@
 #ifndef MOJO_PUBLIC_CPP_ENVIRONMENT_DEFAULT_ASYNC_WAITER_H_
 #define MOJO_PUBLIC_CPP_ENVIRONMENT_DEFAULT_ASYNC_WAITER_H_
 
-#include "mojo/public/c/system/async_waiter.h"
+#include "mojo/public/c/environment/async_waiter.h"
 
 namespace mojo {
 
diff --git a/mojo/public/gles2/gles2_private.h b/mojo/public/gles2/gles2_private.h
index 591e043..c92f555 100644
--- a/mojo/public/gles2/gles2_private.h
+++ b/mojo/public/gles2/gles2_private.h
@@ -7,9 +7,9 @@
 
 #include <stdint.h>
 
+#include "mojo/public/c/environment/async_waiter.h"
 #include "mojo/public/c/gles2/gles2_export.h"
 #include "mojo/public/c/gles2/gles2_types.h"
-#include "mojo/public/c/system/async_waiter.h"
 #include "mojo/public/cpp/system/core.h"
 
 namespace mojo {