Add some documentation

Summary: Adds documentation about the Inspector.

Reviewed By: passy, foghina

Differential Revision: D4114673

fbshipit-source-id: fb1182c89c94f10a74d4589b6a24a06b376db92e

ReactCommon/inspector/Agent.h

@@ -9,6 +9,9 @@
 namespace facebook {
 namespace react {
 
+/*
+ * An dispatcher that makes it simple to implement an agent that serves a single domain.
+ */
 class Agent : public Dispatcher {
 public:
   void onConnect(std::shared_ptr<Channel> channel) override;

ReactCommon/inspector/ConsoleAgent.h

@@ -17,6 +17,10 @@ class InjectedScriptManager;
 namespace facebook {
 namespace react {
 
+/**
+ * Implements the Console agent. Relies on Javascript to call the globally exposed method __inspectorLog
+ * to send logging events.
+ */
 class ConsoleAgent : public Agent {
 public:
   ConsoleAgent(JSC::JSGlobalObject& globalObject, Inspector::InjectedScriptManager* injectedScriptManager);

ReactCommon/inspector/Dispatcher.h

@@ -11,6 +11,10 @@
 namespace facebook {
 namespace react {
 
+/*
+ * A bidrectional channel that allows both sending events to the remote inspector and registering
+ * to receive events for a specific domain.
+ */
 class Channel {
 public:
   using MessageHandler = std::function<void(std::string message, int callId, const std::string& methodName, folly::dynamic args)>;
@@ -21,6 +25,10 @@ public:
   virtual void registerDomain(std::string domain, MessageHandler handler) = 0;
 };
 
+/*
+ * A dispatcher is responsible for one or multiple domains and registering them with the Channel
+ * when it is connected.
+ */
 class Dispatcher {
 public:
   virtual ~Dispatcher() {}

ReactCommon/inspector/Inspector.h

@@ -16,7 +16,11 @@ namespace react {
 
 class InspectorController;
 class Sender;
-
+/**
+ * The inspector exposes method to query for available 'pages' and connect to a specific one.
+ * Available Javascript contextes needs to be registered when they are created and removed when
+ * they are torn down.
+ */
 class Inspector {
 private:
   class DuplexConnection;
@@ -36,7 +40,7 @@ public:
   public:
     void sendMessage(std::string message);
     void disconnect();
-    
+
     LocalConnection(std::shared_ptr<DuplexConnection> duplexConnection);
   private:
     std::shared_ptr<DuplexConnection> duplexConnection_;

ReactCommon/inspector/JSDispatcher.h

@@ -21,6 +21,10 @@ class JSArray;
 namespace facebook {
 namespace react {
 
+/*
+ * A dispatcher that allows agents to be implemented in Javascript. Provides the global method
+ * __registerInspectorAgent to register a JS agent.
+ */
 class JSDispatcher : public Dispatcher {
 public:
   JSDispatcher(JSC::JSGlobalObject& globalObject);

ReactCommon/inspector/LegacyAgents.h

@@ -14,6 +14,9 @@ namespace react {
 class LegacyInspectorEnvironment;
 class ConsoleAgent;
 
+/*
+ * An dispatcher that provides the existing agents in JavaScriptCore.
+ */
 class LegacyAgents : public LegacyDispatcher {
 public:
   LegacyAgents(

ReactCommon/inspector/LegacyDispatcher.h

@@ -20,6 +20,10 @@ class JSGlobalObject;
 namespace facebook {
 namespace react {
 
+/*
+ * An dispatcher that is able to register JavaScriptCore agents that extend the InspectorAgentBase
+ * base class.
+ */
 class LegacyDispatcher : public Dispatcher {
 public:
   LegacyDispatcher(JSC::JSGlobalObject& globalObject);

ReactCommon/inspector/README.md

@@ -0,0 +1,17 @@
+# Inspector
+
+This directory implements an the Chrome debugging protocol [1]. The version used is roughly 1.1 of
+the protocol. The code here doesn't specify a transport and doesn't implement an actual server. This
+is left up to higher parts of the stack.
+
+The implementation uses multiple "dispatchers" to route messages for a specific domain. It reuses
+existing code in JavaScriptCore to handle the domains for Debugger and Runtime. For Console, Page
+and Inspector there are new implementations.
+
+## Open source
+
+The inspector currently doesn't compile in open source. This is due to how the build on Android
+where we download the JSC sources and build an artifact separately, later download the headers we
+need. The number of headers download would have to be expanded and verify that it builds correctly.
+
+[1]: https://developer.chrome.com/devtools/docs/debugger-protocol