Github user stevengill commented on a diff in the pull request:
https://github.com/apache/cordova-lib/pull/331#discussion_r43339044
--- Diff: cordova-common/README.md ---
@@ -20,12 +20,128 @@
-->
# cordova-common
-Contains shared classes and routines used by
[cordova-lib](https://github.com/apache/cordova-lib/) and platforms.
+Expoeses shared functionality used by
[cordova-lib](https://github.com/apache/cordova-lib/) and Cordova platforms.
+## Exposed APIs
+
+### `events`
+
+Represents special instance of NodeJS EventEmitter which is intended to be
used to post events to cordova-lib and cordova-cli
+
+Usage:
+```
+var events = require('cordova-common').events;
+events.emit('warn', 'Some warning message')
+```
+
+There are the following events supported by cordova-cli: `verbose`, `log`,
`info`, `warn`, `error`.
+
+### `CordovaError`
+
+An error class used by Cordova to throw cordova-specific errors. The
CordovaError class is inherited from Error, so CordovaError instances is also
valid Error instances (`instanceof` check succeeds).
+
+Usage:
+
+```
+var CordovaError = require('cordova-common').CordovaError;
+throw new CordovaError('Some error message', SOME_ERR_CODE);
+```
+
+See [CordovaError](src/CordovaError/CordovaError.js) for supported error
codes.
+
+### `ConfigParser`
+
+Exposes functionality to deal with cordova project `config.xml` files. For
ConfigParser API reference check [ConfigParser
Readme](src/ConfigParser/README.md).
+
+Usage:
+```
+var ConfigParser = require('cordova-common').ConfigParser;
+var appConfig = new ConfigParser('path/to/cordova-app/config.xml');
+console.log(appconfig.name() + ':' + appConfig.version());
+```
+
+### `PluginInfoProvider` and `PluginInfo`
+
+`PluginInfo` is a wrapper for cordova plugins' `plugin.xml` files. This
class may be instantiated directly or via `PluginInfoProvider`. The difference
is that `PluginInfoProvider` caches `PluginInfo` instances based on plugin
source directory.
+
+Usage:
+```
+var PluginInfo: require('cordova-common').PluginInfo;
+var PluginInfoProvider: require('cordova-common').PluginInfoProvider;
+
+// The following instances are equal
+var plugin1 = new PluginInfo('path/to/plugin_directory');
+var plugin2 = new PluginInfoProvider().get('path/to/plugin_directory');
+
+console.log('The plugin ' + plugin1.id + ' has version ' + plugin1.version)
+```
+
+### `ActionStack`
+
+Utility module for dealing with sequential tasks. Allow to provide a set
of tasks needs to be done and reverts all tasks that already completed if one
of tasks is failed to complete. Used internally by cordova-lib and platforms
plugin installation routines.
+
+Usage:
+```
+var ActionStack = require('cordova-common').ActionStack;
+var stack = new ActionStack()
+
+var action1 = stack.createAction(task1, [<task parameters>],
task1_reverter, [<reverter_parameters>]);
+var action2 = stack.createAction(task2, [<task parameters>],
task2_reverter, [<reverter_parameters>]);
+
+stack.push(action1);
+stack.push(action2);
+
+stack.process()
+.then(function() {
+ // all actions succeded
+})
+.catch(function(error){
+ // One of actions failed with error
+})
+```
+
+### `superspawn`
+
+Module for spawning child processes with some advanced logic.
+
+Usage:
+```
+var superspawn = require('cordova-common').superspawn;
+superspawn.spawn('adb', ['devices'])
+.then(function(devices){
+ // Do something...
+})
+```
+
+### `xmlHelpers`
+
+A set of utility methods for dealing with xml files.
+
+Usage:
+```
+var xml = require('cordova-common').xmlHelpers;
+
+var xmlDoc1 = xml.parseElementtreeSync('some/xml/file');
+var xmlDoc2 = xml.parseElementtreeSync('another/xml/file');
+
+xml.mergeXml(doc1, doc2); // doc2 now contains all the nodes from doc1
+```
+
+### Other APIs
+
+The APIs listed below is also exposed but is intended to be used only
internally by cordova plugin installation routines.
--- End diff --
The APIs listed below are also exposed but are intended to be only used
internally by cordova plugin installation routines.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
