Issue 49 - Automate documentation generation

.gitignore

@@ -2,6 +2,7 @@ SabreDAV/
 
 /*.zip
 /coverage/
+/doc/
 /dav.js
 /dav.js.map
 /dav.min.js

Makefile

@@ -25,6 +25,11 @@ coverage: node_modules
 	cat ./coverage/lcov.info | ./node_modules/.bin/coveralls
 	rm -rf ./coverage
 
+.PHONY: doc
+doc: node_modules
+	rm -rf doc/
+	./node_modules/.bin/jsdoc -r -d doc/ lib/
+
 .PHONY: lint
 lint: node_modules
 	./node_modules/.bin/jshint --verbose lib/ test/

lib/accounts.js

@@ -1,3 +1,6 @@
+/**
+ * @module accounts
+ */
 'use strict';
 
 var calendars = require('./calendars'),
@@ -12,6 +15,7 @@ var calendars = require('./calendars'),
  * rfc 6764.
  *
  * @param {dav.Account} account to find root url for.
+ * @access private
  */
 function serviceDiscovery(account, options) {
   debug('Attempt service discovery.');
@@ -53,6 +57,7 @@ function serviceDiscovery(account, options) {
  * rfc 5397.
  *
  * @param {dav.Account} account to get principal url for.
+ * @access private
  */
 function principalUrl(account, options) {
   debug('Fetch principal url from context path ' + account.rootUrl + '.');
@@ -75,6 +80,7 @@ function principalUrl(account, options) {
 
 /**
  * @param {dav.Account} account to get home url for.
+ * @access private
  */
 function homeUrl(account, options) {
   debug('Fetch home url from principal url ' + account.principalUrl + '.');
@@ -111,6 +117,7 @@ function homeUrl(account, options) {
 
 /**
  * @param {dav.DAVCollection} collection to fetch report set for.
+ * @access private
  */
 function supportedReportSet(collection, options) {
   debug('Checking supported report set for collection at ' + collection.url);
@@ -128,6 +135,7 @@ function supportedReportSet(collection, options) {
 
 /**
  * @param {dav.Account} account to fetch calendars for.
+ * @access private
  */
 function fetchCalendars(account, options) {
   debug('Fetch calendars from home url ' + account.homeUrl);
@@ -191,6 +199,7 @@ function fetchCalendars(account, options) {
 
 /**
  * @param {dav.Account} account to fetch address books for.
+ * @access private
  */
 function fetchAddressBooks(account, options) {
   debug('Fetch address books from home url ' + account.homeUrl);

lib/calendars.js

@@ -1,3 +1,6 @@
+/**
+ * @module calendars
+ */
 'use strict';
 
 var debug = require('debug')('dav:calendars'),
@@ -7,7 +10,7 @@ var debug = require('debug')('dav:calendars'),
     url = require('url');
 
 /**
- * @param {dav.Calendar} calendar the calendar to put the object on.
+ * @param {model.Calendar} calendar the calendar to put the object on.
  * @return {Promise} promise will resolve when the calendar has been created.
  *
  * Options:
@@ -28,7 +31,7 @@ exports.createCalendarObject = function(calendar, options) {
 };
 
 /**
- * @param {dav.CalendarObject} calendarObject updated calendar object.
+ * @param {model.CalendarObject} calendarObject updated calendar object.
  * @return {Promise} promise will resolve when the calendar has been updated.
  *
  * Options:
@@ -49,7 +52,7 @@ exports.updateCalendarObject = function(calendarObject, options) {
 };
 
 /**
- * @param {dav.CalendarObject} calendarObject target calendar object.
+ * @param {model.CalendarObject} calendarObject target calendar object.
  * @return {Promise} promise will resolve when the calendar has been deleted.
  *
  * Options:
@@ -69,15 +72,15 @@ exports.deleteCalendarObject = function(calendarObject, options) {
 };
 
 /**
- * @param {dav.Calendar} calendar the calendar to fetch objects for.
+ * @param {model.Calendar} calendar the calendar to fetch objects for.
  *
  * Options:
  *
  *   (Array.<Object>) filters - optional caldav filters.
  *   (dav.Sandbox) sandbox - optional request sandbox.
  *   (dav.Transport) xhr - request sender.
  */
-function fetchObjects(calendar, options) {
+var fetchObjects = exports.fetchObjects = function(calendar, options) {
   debug('Doing REPORT on calendar ' + calendar.url +
         ' which belongs to ' + calendar.account.credentials.username);
 
@@ -112,9 +115,11 @@ function fetchObjects(calendar, options) {
       });
     });
   });
-}
-exports.fetchObjects = fetchObjects;
+};
 
+/**
+ * @access private
+ */
 function basicSync(calendar, options) {
   return new Promise(function(resolve, reject) {
     if (!calendar.ctag) {
@@ -165,6 +170,9 @@ function basicSync(calendar, options) {
   });
 }
 
+/**
+ * @access private
+ */
 function webdavSync(calendar, options) {
   var req = request.syncCollection({
     props: [
@@ -200,7 +208,7 @@ function webdavSync(calendar, options) {
 }
 
 /**
- * @param {dav.Calendar} calendar the calendar to fetch updates to.
+ * @param {model.Calendar} calendar the calendar to fetch updates to.
  * @return {Promise} promise will resolve with updated calendar object.
  *
  * Options:

lib/camelize.js

@@ -3,6 +3,9 @@
  */
 'use strict';
 
+/**
+ * @access private
+ */
 module.exports = function(str, delimiter) {
   delimiter = delimiter || '_';
   var words = str.split(delimiter);

lib/client.js

@@ -1,3 +1,6 @@
+/**
+ * @class Client
+ */
 'use strict';
 
 var accounts = require('./accounts'),
@@ -6,6 +9,7 @@ var accounts = require('./accounts'),
     url = require('url');
 
 /**
+ * @constructor
  * @param {dav.Transport} xhr - request sender.
  *
  * Options:

lib/contacts.js

@@ -1,3 +1,6 @@
+/**
+ * @module contacts
+ */
 'use strict';
 
 var debug = require('debug')('dav:contacts'),
@@ -7,7 +10,8 @@ var debug = require('debug')('dav:contacts'),
     url = require('url');
 
 /**
- * @param {dav.AddressBook} addressBook the address book to put the object on.
+ * @param {model.AddressBook} addressBook the address book
+ *     to put the object on.
  * @return {Promise} promise will resolve when the card has been created.
  *
  * Options:
@@ -28,7 +32,7 @@ exports.createCard = function(addressBook, options) {
 };
 
 /**
- * @param {dav.VCard} card updated vcard object.
+ * @param {model.VCard} card updated vcard object.
  * @return {Promise} promise will resolve when the card has been updated.
  *
  * Options:
@@ -47,7 +51,7 @@ exports.updateCard = function(card, options) {
 };
 
 /**
- * @param {dav.VCard} card target vcard object.
+ * @param {model.VCard} card target vcard object.
  * @return {Promise} promise will resolve when the calendar has been deleted.
  *
  * Options:
@@ -65,11 +69,13 @@ exports.deleteCard = function(card, options) {
 };
 
 /**
+ * @param {model.AddressBook} addressBook to fetch objects for.
+ *
  * Options:
  *
  *   (dav.Sandbox) sandbox - optional request sandbox.
  */
-function fetchObjects(addressBook, options) {
+var fetchObjects = exports.fetchObjects = function(addressBook, options) {
   debug('Doing REPORT on address book ' + addressBook.url +
         'which belongs to ' + addressBook.account.credentials.username);
 
@@ -94,9 +100,11 @@ function fetchObjects(addressBook, options) {
       });
     });
   });
-}
-exports.fetchObjects = fetchObjects;
+};
 
+/**
+ * @access private
+ */
 function basicSync(addressBook, options) {
   return new Promise(function(resolve, reject) {
     if (!addressBook.ctag) {
@@ -146,6 +154,9 @@ function basicSync(addressBook, options) {
   });
 }
 
+/**
+ * @access private
+ */
 function webdavSync(addressBook, options) {
   var req = request.syncCollection({
     props: [
@@ -179,7 +190,7 @@ function webdavSync(addressBook, options) {
 }
 
 /**
- * @param {dav.Calendar} calendar the calendar to fetch updates to.
+ * @param {model.AddressBook} addressBook the address book to fetch updates to.
  * @return {Promise} promise will resolve with updated calendar object.
  *
  * Options:

lib/index.js

@@ -1,63 +1,88 @@
+/**
+ * @module dav
+ */
 'use strict';
 
 var Client = require('./client'),
-    Sandbox = require('./sandbox'),
     accounts = require('./accounts'),
     calendars = require('./calendars'),
     contacts = require('./contacts'),
     model = require('./model'),
     request = require('./request'),
+    sandbox = require('./sandbox'),
     transport = require('./transport');
 
-/**
- * model
- */
-for (var key in model) {
-  exports[key] = model[key];
-}
+/** {@link model.Account} */
+exports.Account = model.Account;
 
-/**
- * accounts
- */
+/** {@link model.AddressBook} */
+exports.AddressBook = model.AddressBook;
+
+/** {@link model.Calendar} */
+exports.Calendar = model.Calendar;
+
+/** {@link model.CalendarObject} */
+exports.CalendarObject = model.CalendarObject;
+
+/** {@link model.Credentials} */
+exports.Credentials = model.Credentials;
+
+/** {@link model.DAVCollection} */
+exports.DAVCollection = model.DAVCollection;
+
+/** {@link model.DAVObject} */
+exports.DAVObject = model.DAVObject;
+
+/** {@link model.Model} */
+exports.Model = model.Model;
+
+/** {@link model.VCard} */
+exports.VCard = model.VCard;
+
+/** {@link module:accounts.create} */
 exports.createAccount = accounts.create;
 
-/**
- * calendars
- */
+/** {@link module:calendars.createCalendarObject} */
 exports.createCalendarObject = calendars.createCalendarObject;
+
+/** {@link module:calendars.updateCalendarObject} */
 exports.updateCalendarObject = calendars.updateCalendarObject;
+
+/** {@link module:calendars.deleteCalendarObject} */
 exports.deleteCalendarObject = calendars.deleteCalendarObject;
+
+/** {@link module:calendars.sync} */
 exports.syncCalendar = calendars.sync;
 
-/**
- * contacts
- */
+/** {@link module:contacts.createCard} */
 exports.createCard = contacts.createCard;
+
+/** {@link module:contacts.updateCard} */
 exports.updateCard = contacts.updateCard;
+
+/** {@link module:contacts.deleteCard} */
 exports.deleteCard = contacts.deleteCard;
+
+/** {@link module:contacts.sync} */
 exports.syncAddressBook = contacts.sync;
 
-/**
- * client
- */
+/** {@link Client} */
 exports.Client = Client;
 
-/**
- * request
- */
+/** {@link request} */
 exports.request = request;
+
+/** {@link request.Request} */
 exports.Request = request.Request;
 
-/**
- * sandbox
- */
-exports.createSandbox = function() {
-  return new Sandbox();
-};
-exports.Sandbox = Sandbox;
+/** {@link module:sandbox.Sandbox} */
+exports.Sandbox = sandbox.Sandbox;
 
-/**
- * transport
- */
+/** {@link module:sandbox.createSandbox} */
+exports.createSandbox = sandbox.createSandbox;
+
+/** {@link transport} */
 exports.transport = transport;
+
+/** {@link transport.Transport} */
 exports.Transport = transport.Transport;