Merge pull request #705 from mapnik/plugin-docs

mapnik plugin docs

package.json

@@ -51,7 +51,7 @@
     "test": "jshint bin lib/index.js lib/mapnik.js && mocha -R spec --timeout 50000",
     "preinstall":"npm install node-pre-gyp",
     "install": "node-pre-gyp install --fallback-to-build",
-    "docs": "documentation build src/*.cpp --polyglot -o documentation -f html --github --name Mapnik"
+    "docs": "documentation build src/*.cpp src/mapnik_plugins.hpp --polyglot -o documentation -f html --github --name Mapnik"
   },
   "devDependencies": {
     "aws-sdk": "2.0.12",

src/mapnik_plugins.hpp

@@ -15,6 +15,24 @@
 
 namespace node_mapnik {
 
+/**
+ * Register all plugins available. This is not recommend in environments where high-performance is priority.
+ * Consider registering plugins on a per-need basis.
+ * 
+ * @memberof mapnik
+ * @name register_default_input_plugins
+ * @example
+ * var mapnik = require('mapnik');
+ * mapnik.register_default_input_plugins();
+ */
+
+/**
+ * List all plugins that are currently available.
+ *
+ * @memberof mapnik
+ * @name datasources
+ * @returns {Array<String>} list of plugins available to use
+ */
 static inline NAN_METHOD(available_input_plugins)
 {
     std::vector<std::string> names = mapnik::datasource_cache::instance().plugin_names();
@@ -26,6 +44,26 @@ static inline NAN_METHOD(available_input_plugins)
     info.GetReturnValue().Set(a);
 }
 
+/**
+ * Register a single datasource input plugin. The available plugins are:
+ *
+ * * `'csv.input'`
+ * * `'gdal.input'`
+ * * `'geojson.input'`
+ * * `'ogr.input'`
+ * * `'pgraster.input'`
+ * * `'postgis.input'`
+ * * `'raster.input'`
+ * * `'shape.input'`
+ * * `'sqlite.input'`
+ * * `'topojson.input'`
+ *
+ * @memberof mapnik
+ * @name registerDatasource
+ * @param {String} path to a datasource to register.
+ * @example
+ * mapnik.registerDatasource(path.join(mapnik.settings.paths.input_plugins, 'geojson.input'));
+ */
 static inline NAN_METHOD(register_datasource)
 {
     if (info.Length() != 1 || !info[0]->IsString())
@@ -45,6 +83,13 @@ static inline NAN_METHOD(register_datasource)
     info.GetReturnValue().Set(Nan::False());
 }
 
+/**
+ * Register multiple datasources.
+ *
+ * @memberof mapnik
+ * @name registerDatasources
+ * @param {Array<String>} list of paths to their respective datasources
+ */
 static inline NAN_METHOD(register_datasources)
 {
     if (info.Length() != 1 || !info[0]->IsString())

src/node_mapnik.cpp

@@ -72,6 +72,21 @@ static NAN_METHOD(clearCache)
  * Mapnik is the core of cartographic design and processing. `node-mapnik` provides a
  * set of bindings to `mapnik` for node.js.
  *
+ * ### Plugins
+ * 
+ * Node Mapnik relies on a set of datasource input plugins that must be configured prior to using the API.
+ * These plugins are either built into Mapnik, such as the "geojson" plugin
+ * or rely on exeternal dependencies, such as GDAL. All plugin methods exist on the `mapnik` 
+ * class level.
+ *
+ * Plugins are referenced based on the location of the bindings on your system. These paths are generated
+ * in the lib/binding/{build}/mapnik_settings.js file. These settings can be referenced by the `mapnik.settings` object. We recommend using the `require('path')`
+ * object when building these paths:
+ * 
+ * ```
+ * path.resolve(mapnik.settings.paths.input_plugins, 'geojson.input')
+ * ```
+ *
  * @name mapnik
  * @class mapnik
  * @property {string} version current version of mapnik
@@ -80,6 +95,22 @@ static NAN_METHOD(clearCache)
  * grid, svg, cairo, cairo_pdf, cairo_svg, png, jpeg, tiff, webp, proj4, threadsafe
  * @property {Object} versions diagnostic object with versions of
  * node, v8, boost, boost_number, mapnik, mapnik_number, mapnik_git_describe, cairo
+ * @property {Object} settings - object that defines local paths for particular plugins and addons. 
+ * 
+ * ```
+ * // mapnik.settings on OSX
+ * { 
+ *   paths: { 
+ *     fonts: '/Users/username/mapnik/node_modules/mapnik/lib/binding/node-v46-darwin-x64/mapnik/fonts',
+ *     input_plugins: '/Users/username/mapnik/node_modules/mapnik/lib/binding/node-v46-darwin-x64/mapnik/input' 
+ *   },
+ *   env: { 
+ *     ICU_DATA: '/Users/username/mapnik/node_modules/mapnik/lib/binding/node-v46-darwin-x64/share/mapnik/icu',
+ *     GDAL_DATA: '/Users/username/mapnik/node_modules/mapnik/lib/binding/node-v46-darwin-x64/share/mapnik/gdal',
+ *     PROJ_LIB: '/Users/username/mapnik/node_modules/mapnik/lib/binding/node-v46-darwin-x64/share/mapnik/proj' 
+ *   }
+ * }
+ * ```
  * @example
  * var mapnik = require('mapnik');
  */