docs: Added missing documentation (based on yuidocjs)

build_docs.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+yuidoc -e .js,.h . -o docs

can.js

@@ -25,18 +25,40 @@
 var can = require('./build/Release/can');
 var buffer = require('buffer');
 
-// Exports
+/**
+ * @method createRawChannel
+ * @param channel {string} Channel name (e.g. vcan0)
+ * @return {RawChannel} a new channel object or exception
+ * @for exports
+ */
 exports.createRawChannel = function(channel, timestamps) { return new can.RawChannel(channel, timestamps); }
 
 //-----------------------------------------------------------------------------
-// Signal-Object
+/**
+ * The Signals modules provides an interface to access the values/signals
+ * encoded in CAN messages.
+ * @module Signals
+ */
+
+/**
+ * @method hans
+ */
 
 var _signals = require('./build/Release/can_signals');
 
 var kcd = require('./parse_kcd');
 
+/**
+ * The actual signal.
+ * @class Signal
+ */
 function Signal(desc)
 {
+        /**
+         * Symbolic name
+         * @attribute name
+         * @final
+         */
 	this.name = desc['name'];
 
 	this.bitOffset = desc['bitOffset'];
@@ -50,19 +72,36 @@ function Signal(desc)
 	this.minValue = desc['minValue'];
 	this.maxValue = desc['maxValue'];
 
+        /**
+         * Current value
+         * @attribute value
+         * @final
+         */
 	this.value = desc['defaultValue'];
 	if (!this.value)
 		this.value = 0;
 
 	this.listeners = [];
 }
 
-// Keep track of listeners who want to be notified if this signal changes
+/**
+ * Keep track of listeners who want to be notified if this signal changes
+ * @method onChange
+ * @param listener JS callback to get notification
+ * @for Signal
+ */
 Signal.prototype.onChange = function(listener) {
 	this.listeners.push(listener);
 }
 
-// Someone wants to change signals' value
+/**
+ * Set new value of this signal. Any local registered clients will
+ * receive a notification. Please note, no CAN message is actually
+ * send to the bus (@see DatabaseServer::send)
+ * @method update
+ * @param newValue {bool|double|integer} New value to set
+ * @for Signal
+ */
 Signal.prototype.update = function(newValue) {
 	// Nothing changed
 	if (this.value == newValue)
@@ -77,16 +116,45 @@ Signal.prototype.update = function(newValue) {
 }
 
 //-----------------------------------------------------------------------------
-// Message-Object
+/**
+ * Just a container to keep the Signals.
+ * @class Message
+ */
 function Message(desc)
 {
+        /**
+         * CAN identifier
+         * @attribute id
+         * @final
+         */
 	this.id = desc.id;
+
+	/**
+         * Extended Frame Format used
+         * @attribute ext
+         * @final
+         */
 	this.ext = desc.ext;
 
+        /**
+         * Symbolic name
+         * @attribute name
+         * @final
+         */
 	this.name = desc.name;
 
+        /**
+         * Length in bytes of resulting CAN message
+         * @attribute length
+         * @final
+         */
 	this.length = desc.length;
 
+        /**
+         * Named array of signals within this message. Accessible via index and name.
+         * @attribute {Signal} signals
+         * @final
+         */
 	this.signals = [];
 
 	for (i in desc['signals']) {
@@ -96,10 +164,23 @@ function Message(desc)
 }
 
 //-----------------------------------------------------------------------------
-// DatabaseService
+/**
+ * A DatabaseService is usually generated once per bus to collect signals
+ * coded in the CAN messages according a DB description.
+ * @class DatabaseService
+ * @constructor DatabaseService
+ * @param channel RAW channel
+ * @param db_desc Set of rules to decode/encode signals (@parse_kcd.js)
+ * @return a new DatabaseService
+ * @for DatabaseService
+ */
 function DatabaseService(channel, db_desc) {
 	this.channel = channel;
 
+        /**
+         * Named array of known messages. Accessible via index and name.
+         * @attribute {Message} messages
+         */
 	this.messages = [];
 
 	for (i in db_desc) {
@@ -111,9 +192,11 @@ function DatabaseService(channel, db_desc) {
 		this.messages[m.name] = nm;
 	}
 
+	// Subscribe to any incoming messages
 	channel.addListener("onMessage", this.onMessage, this);
 }
 
+// Callback for incoming messages
 DatabaseService.prototype.onMessage = function (msg) {
 	if (msg.rtr)
 		return;
@@ -143,6 +226,13 @@ DatabaseService.prototype.onMessage = function (msg) {
 	}
 }
 
+/**
+ * Construct a CAN message and encode all related signals according
+ * the rules. Finally send the message to the bus.
+ * @method send
+ * @param msg_name Name of the message to generate
+ * @for DatabaseService
+ */
 DatabaseService.prototype.send = function (msg_name) {
 	var m = this.messages[msg_name]
 
@@ -180,7 +270,12 @@ DatabaseService.prototype.send = function (msg_name) {
 	this.channel.send(canmsg);
 }
 
-// Exports
+/**
+ * @method parseNetworkDescription
+ * @param file {string} Path to KCD file to parse
+ * @return DB description to be used in DatabaseService
+ * @for exports
+ */
 exports.parseNetworkDescription = kcd.parseKcdFile;
 exports.DatabaseService = DatabaseService;
 

docs/api.js

@@ -0,0 +1,27 @@
+YUI.add("yuidoc-meta", function(Y) {
+   Y.YUIDoc = { meta: {
+    "classes": [
+        "DatabaseService",
+        "Message",
+        "RawChannel",
+        "Signal",
+        "exports"
+    ],
+    "modules": [
+        "CAN",
+        "Signals"
+    ],
+    "allModules": [
+        {
+            "displayName": "CAN",
+            "name": "CAN",
+            "description": "Basic CAN access"
+        },
+        {
+            "displayName": "Signals",
+            "name": "Signals",
+            "description": "The Signals modules provides an interface to access the values/signals\nencoded in CAN messages."
+        }
+    ]
+} };
+});