Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Made final changes to code documentation for JSDoc

  • Loading branch information...
commit edd6d40e828e0b4b82fba7ca22b4857bdb1256bc 1 parent 223f18a
@larzconwell larzconwell authored
Showing with 147 additions and 84 deletions.
  1. +16 −0 .gitignore
  2. +11 −19 lib/array.js
  3. +92 −42 lib/date.js
  4. +17 −19 lib/object.js
  5. +11 −4 lib/xml.js
View
16 .gitignore
@@ -0,0 +1,16 @@
+v8.log
+*.swp
+*.swo
+auth_info.js
+dist
+.idea/
+tags
+nbproject/
+spec/browser/autogen_suite.js
+node_modules
+tmtags
+*.DS_Store
+examples/*/log/*
+.log
+npm-debug.log
+doc/
View
30 lib/array.js
@@ -16,11 +16,17 @@
*
*/
+/**
+ @name array
+ @namespace array
+*/
+
var array = new (function () {
- /*
- @name humanize
+ /**
+ @name array#humanize
@public
+ @function
@return {String} A string containing the array elements in a readable format
@description Creates a string containing the array elements in a readable format
@param {Array} array The array to humanize
@@ -37,24 +43,10 @@ var array = new (function () {
return items + ' and ' + last;
};
- /*
- * included(item<Any>, array<Array>)
- *
- * Included checks if an `item` is included in a `array`
- * if it is found then the `array` is returned, otherwise
- * false is returned
- *
- * Examples:
- * included("array", ["array"])
- * => ["array"]
- *
- * included("nope", ["array"])
- * => false
- */
-
- /*
- @name included
+ /**
+ @name array#included
@public
+ @function
@return {Array/Boolean} If `item` is included the `array` is returned otherwise false
@description Checks if an `item` is included in an `array`
@param {Any} item The item to look for
View
134 lib/date.js
@@ -19,6 +19,11 @@
var string = require('./string')
, date;
+/**
+ @name date
+ @namespace date
+*/
+
date = new (function () {
var _this = this
, _date = new Date();
@@ -55,11 +60,19 @@ date = new (function () {
'October', 'November', 'December'];
this.monthShort = ['Jan', 'Feb', 'Mar', 'Apr',
'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
- this.meridian = {
+ this.meridiem = {
'AM': 'AM',
'PM': 'PM'
}
+ // compat
+ this.meridian = this.meridiem
+ /**
+ @name date#supportedFormats
+ @public
+ @object
+ @description List of supported strftime formats
+ */
this.supportedFormats = {
// abbreviated weekday name according to the current locale
'a': function (dt) { return _this.weekdayShort[dt.getDay()]; },
@@ -167,6 +180,13 @@ date = new (function () {
'%': function (dt) { return '%'; }
};
+ /**
+ @name date#getSupportedFormats
+ @public
+ @function
+ @description return the list of formats in a string
+ @return {String} The list of supported formats
+ */
this.getSupportedFormats = function () {
var str = '';
for (var i in this.supportedFormats) { str += i; }
@@ -176,6 +196,15 @@ date = new (function () {
this.supportedFormatsPat = new RegExp('%[' +
this.getSupportedFormats() + ']{1}', 'g');
+ /**
+ @name date#strftime
+ @public
+ @function
+ @return {String} The `dt` formated with the given `format`
+ @description Formats the given date with the strftime format
+ @param {Date} dt the date object to format
+ @param {String} format the format to convert the date to
+ */
this.strftime = function (dt, format) {
if (!dt) { return '' }
@@ -211,10 +240,13 @@ date = new (function () {
};
/**
- * Calculate the century to which a particular year belongs
- * @param year Integer year number
- * @return Integer century number
- */
+ @name date#calcCentury
+ @public
+ @function
+ @return {String} The century for the given date
+ @description Find the century for the given `year`
+ @param {String} year The year to find the century for
+ */
this.calcCentury = function (year) {
if(!year) {
year = _date.getFullYear();
@@ -233,10 +265,13 @@ date = new (function () {
};
/**
- * Calculate the day number in the year a particular date is on
- * @param dt JavaScript date object
- * @return Integer day number in the year for the given date
- */
+ @name date#calcDays
+ @public
+ @function
+ @return {Number} The number of days so far for the given date
+ @description Calculate the day number in the year a particular date is on
+ @param {Date} dt The date to use
+ */
this.calcDays = function(dt) {
var first = new Date(dt.getFullYear(), 0, 1);
var diff = 0;
@@ -267,22 +302,28 @@ date = new (function () {
};
/**
- * Return 'AM' or 'PM' based on hour in 24-hour format
- * @param h Integer for hour in 24-hour format
- * @return String of either 'AM' or 'PM' based on hour number
- */
+ @name date#getMeridiem
+ @public
+ @function
+ @return {String} Return 'AM' or 'PM' based on hour in 24-hour format
+ @description Return 'AM' or 'PM' based on hour in 24-hour format
+ @param {Number} h The hour to check
+ */
this.getMeridiem = function (h) {
- return h > 11 ? this.meridian.PM :
- this.meridian.AM;
+ return h > 11 ? this.meridiem.PM :
+ this.meridiem.AM;
};
- // Compat for mispelled version
+ // Compat
this.getMeridian = this.getMeridiem;
/**
- * Convert a 24-hour formatted hour to 12-hour format
- * @param hour Integer hour number
- * @return String for hour in 12-hour format -- may be string length of one
- */
+ @name date#hrMil2Std
+ @public
+ @function
+ @return {String} Return a 12 hour version of the given time
+ @description Convert a 24-hour formatted hour to 12-hour format
+ @param {String} hour The hour to convert
+ */
this.hrMil2Std = function (hour) {
var h = typeof hour == 'number' ? hour : parseInt(hour);
var str = h > 12 ? h - 12 : h;
@@ -291,11 +332,14 @@ date = new (function () {
};
/**
- * Convert a 12-hour formatted hour with meridian flag to 24-hour format
- * @param hour Integer hour number
- * @param pm Boolean flag, if PM hour then set to true
- * @return String for hour in 24-hour format
- */
+ @name date#hrStd2Mil
+ @public
+ @function
+ @return {String} Return a 24 hour version of the given time
+ @description Convert a 12-hour formatted hour with meridian flag to 24-hour format
+ @param {String} hour The hour to convert
+ @param {Boolean} If hour is PM then this should be true
+ */
this.hrStd2Mil = function (hour, pm) {
var h = typeof hour == 'number' ? hour : parseInt(hour);
var str = '';
@@ -332,14 +376,17 @@ date = new (function () {
this.dateParts = dateParts;
/**
- * Add to a Date in intervals of different size, from
- * milliseconds to years
- * @param dt -- Date (or timestamp Number), date to increment
- * @param interv -- String, a constant representing the interval,
- * e.g. YEAR, MONTH, DAY. See this.dateParts
- * @param incr -- Number, how much to add to the date
- * @return Integer day number for 1-7 base week
- */
+ @name date#add
+ @public
+ @function
+ @return {Number} Day number from 1-7
+ @description Add to a Date in intervals of different size, from
+ milliseconds to years
+ @param {Date} dt Date (or timestamp Number), date to increment
+ @param {String} interv a constant representing the interval,
+ e.g. YEAR, MONTH, DAY. See this.dateParts
+ @param {Number} incr how much to add to the date
+ */
this.add = function (dt, interv, incr) {
if (typeof dt == 'number') { dt = new Date(dt); }
function fixOvershoot(){
@@ -434,15 +481,18 @@ date = new (function () {
};
/**
- * Get the difference in a specific unit of time (e.g., number
- * of months, weeks, days, etc.) between two dates.
- * @param date1 -- Date (or timestamp Number)
- * @param date2 -- Date (or timestamp Number)
- * @param interv -- String, a constant representing the interval,
- * e.g. YEAR, MONTH, DAY. See this.dateParts
- * @return Integer, number of (interv) units apart that
- * the two dates are
- */
+ @name date#diff
+ @public
+ @function
+ @return {Number} number of (interv) units apart that
+ the two dates are
+ @description Get the difference in a specific unit of time (e.g., number
+ of months, weeks, days, etc.) between two dates.
+ @param {Date} date1 First date to check
+ @param {Date} date2 Date to compate `date1` with
+ @param {String} interv a constant representing the interval,
+ e.g. YEAR, MONTH, DAY. See this.dateParts
+ */
this.diff = function (date1, date2, interv) {
// date1
// Date object or Number equivalent
View
36 lib/object.js
@@ -16,11 +16,17 @@
*
*/
+/**
+ @name object
+ @namespace object
+*/
+
var object = new (function () {
- /*
- @name merge
+ /**
+ @name object#merge
@public
+ @function
@return {Object} Returns the merged object
@description Merge merges `otherObject` into `object` and takes care of deep
merging of objects
@@ -49,9 +55,10 @@ var object = new (function () {
return object;
};
- /*
- @name reverseMerge
+ /**
+ @name object#reverseMerge
@public
+ @function
@return {Object} Returns the merged object
@description ReverseMerge merges `object` into `defaultObject`
@param {Object} object Object to read from
@@ -63,9 +70,10 @@ var object = new (function () {
return this.merge(defaultObject, object);
};
- /*
- @name isEmpty
+ /**
+ @name object#isEmpty
@public
+ @function
@return {Boolean} Returns true if empty false otherwise
@description isEmpty checks if an Object is empty
@param {Object} object Object to check if empty
@@ -76,20 +84,10 @@ var object = new (function () {
return true;
};
- /*
- * toArray(object<Object>)
- *
- * ToArray takes each key/value in the `object` and puts in array with the value
- * as an object with the original key and value
- *
- * Examples:
- * toArray({ex: "json"})
- * => [{key: "ex", value: "json"}]
- */
-
- /*
- @name toArray
+ /**
+ @name object#toArray
@public
+ @function
@return {Array} Returns an array of objects each including the original key and value
@description Converts an object to an array of objects each including the original key/value
@param {Object} object Object to convert
View
15 lib/xml.js
@@ -18,6 +18,11 @@
var core = require('./core')
, inflection = require('../deps/inflection')
+/**
+ @name xml
+ @namespace xml
+*/
+
exports.XML = new (function () {
// Default indention level
@@ -217,9 +222,10 @@ exports.XML = new (function () {
, arrayRoot: true
};
- /*
- @name setIndentLevel
+ /**
+ @name xml#setIndentLevel
@public
+ @function
@return {Number} Return the given `level`
@description SetIndentLevel changes the indent level for XML.stringify and returns it
@param {Number} level The indent level to use
@@ -232,9 +238,10 @@ exports.XML = new (function () {
return indentLevel = level;
};
- /*
- @name stringify
+ /**
+ @name xml#stringify
@public
+ @function
@return {String} Return the XML entities of the given `obj`
@description Stringify returns an XML representation of the given `obj`
@param {Object} obj The object containing the XML entities to use
Please sign in to comment.
Something went wrong with that request. Please try again.