Merge 7de7eac into a7c1359

src/lib/AsCallback.coffee

@@ -1,14 +1,35 @@
 #     NoFlo - Flow-Based Programming for JavaScript
 #     (c) 2017 Flowhub UG
 #     NoFlo may be freely distributed under the MIT license
-#
-# asCallback helper embedding NoFlo components or graphs in other JavaScript programs.
 ComponentLoader = require('./ComponentLoader').ComponentLoader
 Network = require('./Network').Network
 IP = require('./IP')
 internalSocket = require './InternalSocket'
 Graph = require('fbp-graph').Graph
 
+# ## asCallback embedding API
+#
+# asCallback is a helper for embedding NoFlo components or
+# graphs in other JavaScript programs.
+#
+# By using the `noflo.asCallback` function, you can turn any
+# NoFlo component or NoFlo Graph instance into a regular,
+# Node.js-style JavaScript function.
+#
+# Each call to that function starts a new NoFlo network where
+# the given input arguments are sent as IP objects to matching
+# inports. Once the network finishes, the IP objects received
+# from the network will be sent to the callback function.
+#
+# If there was anything sent to an `error` outport, this will
+# be provided as the error argument to the callback.
+
+# ### Option normalization
+#
+# Here we handle the input valus given to the `asCallback`
+# function. This allows passing things like a pre-initialized
+# NoFlo ComponentLoader, or giving the component loading
+# baseDir context.
 normalizeOptions = (options, component) ->
   options = {} unless options
   options.name = component unless options.name
@@ -21,6 +42,11 @@ normalizeOptions = (options, component) ->
   options.raw = false unless options.raw
   options
 
+# ### Network preparation
+#
+# Each invocation of the asCallback-wrapped NoFlo graph
+# creates a new network. This way we can isolate multiple
+# executions of the function in their own contexts.
 prepareNetwork = (component, options, callback) ->
   # If we were given a graph instance, then just create a network
   if typeof component is 'object'
@@ -54,6 +80,16 @@ prepareNetwork = (component, options, callback) ->
       return callback err if err
       callback null, network
 
+# ### Network execution
+#
+# Once network is ready, we connect to all of its exported
+# in and outports and start the network.
+#
+# Input data is sent to the inports, and we collect IP
+# packets received on the outports.
+#
+# Once the network finishes, we send the resulting IP
+# objects to the callback.
 runNetwork = (network, inputs, options, callback) ->
   # Prepare inports
   inPorts = Object.keys network.graph.inports

src/lib/BasePort.coffee

@@ -1,10 +1,13 @@
 #     NoFlo - Flow-Based Programming for JavaScript
 #     (c) 2014-2017 Flowhub UG
 #     NoFlo may be freely distributed under the MIT license
-#
-# Base port type used for options normalization
 {EventEmitter} = require 'events'
 
+# ## NoFlo Port Base class
+#
+# Base port type used for options normalization. Both inports and outports extend this class.
+
+# The list of valid datatypes for ports.
 validTypes = [
   'all'
   'string'
@@ -24,27 +27,39 @@ validTypes = [
 class BasePort extends EventEmitter
   constructor: (options) ->
     super()
-    @handleOptions options
+    # Options holds all options of the current port
+    @options = @handleOptions options
+    # Sockets list contains all currently attached
+    # connections to the port
     @sockets = []
+    # Name of the graph node this port is in
     @node = null
+    # Name of the port
     @name = null
 
   handleOptions: (options) ->
     options = {} unless options
+    # We default to the `all` type if no explicit datatype
+    # was provided
     options.datatype = 'all' unless options.datatype
+    # By default ports are not required for graph execution
     options.required = false if options.required is undefined
 
+    # Normalize the legacy `integer` type to `int`.
     options.datatype = 'int' if options.datatype is 'integer'
+
+    # Ensure datatype defined for the port is valid
     if validTypes.indexOf(options.datatype) is -1
       throw new Error "Invalid port datatype '#{options.datatype}' specified, valid are #{validTypes.join(', ')}"
 
+    # Ensure schema defined for the port is valid
     if options.type and not options.schema
       options.schema = options.type
       delete options.type
     if options.schema and options.schema.indexOf('/') is -1
       throw new Error "Invalid port schema '#{options.schema}' specified. Should be URL or MIME type"
 
-    @options = options
+    options
 
   getId: ->
     unless @node and @name