From fbc8410d86366ff420bdc908097e4a9339ca4b79 Mon Sep 17 00:00:00 2001 From: Alexander Blom Date: Wed, 2 Nov 2016 12:18:19 -0700 Subject: [PATCH] Add some documentation Summary: Adds documentation about the Inspector. Reviewed By: passy, foghina Differential Revision: D4114673 fbshipit-source-id: fb1182c89c94f10a74d4589b6a24a06b376db92e --- ReactCommon/inspector/Agent.h | 3 +++ ReactCommon/inspector/ConsoleAgent.h | 4 ++++ ReactCommon/inspector/Dispatcher.h | 8 ++++++++ ReactCommon/inspector/Inspector.h | 8 ++++++-- ReactCommon/inspector/JSDispatcher.h | 4 ++++ ReactCommon/inspector/LegacyAgents.h | 3 +++ ReactCommon/inspector/LegacyDispatcher.h | 4 ++++ ReactCommon/inspector/README.md | 17 +++++++++++++++++ 8 files changed, 49 insertions(+), 2 deletions(-) create mode 100644 ReactCommon/inspector/README.md diff --git a/ReactCommon/inspector/Agent.h b/ReactCommon/inspector/Agent.h index 598f0f7db..94443231f 100644 --- a/ReactCommon/inspector/Agent.h +++ b/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) override; diff --git a/ReactCommon/inspector/ConsoleAgent.h b/ReactCommon/inspector/ConsoleAgent.h index ffa06ef6d..961271923 100644 --- a/ReactCommon/inspector/ConsoleAgent.h +++ b/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); diff --git a/ReactCommon/inspector/Dispatcher.h b/ReactCommon/inspector/Dispatcher.h index 327942198..c864bea0a 100644 --- a/ReactCommon/inspector/Dispatcher.h +++ b/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; @@ -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() {} diff --git a/ReactCommon/inspector/Inspector.h b/ReactCommon/inspector/Inspector.h index 5d103acae..0f4177b53 100644 --- a/ReactCommon/inspector/Inspector.h +++ b/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); private: std::shared_ptr duplexConnection_; diff --git a/ReactCommon/inspector/JSDispatcher.h b/ReactCommon/inspector/JSDispatcher.h index a957f5a42..b9330301e 100644 --- a/ReactCommon/inspector/JSDispatcher.h +++ b/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); diff --git a/ReactCommon/inspector/LegacyAgents.h b/ReactCommon/inspector/LegacyAgents.h index be3b114e3..36650d7a8 100644 --- a/ReactCommon/inspector/LegacyAgents.h +++ b/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( diff --git a/ReactCommon/inspector/LegacyDispatcher.h b/ReactCommon/inspector/LegacyDispatcher.h index b10553445..96e617d73 100644 --- a/ReactCommon/inspector/LegacyDispatcher.h +++ b/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); diff --git a/ReactCommon/inspector/README.md b/ReactCommon/inspector/README.md new file mode 100644 index 000000000..67da1c7c3 --- /dev/null +++ b/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