cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stevengill <...@git.apache.org>
Subject [GitHub] cordova-lib pull request: CB-9890 Documenting cordova-common
Date Thu, 29 Oct 2015 01:03:08 GMT
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org


Mime
View raw message