diff --git a/build.gradle b/build.gradle index 2d6b33ce..cd997332 100644 --- a/build.gradle +++ b/build.gradle @@ -13,7 +13,7 @@ apply plugin: 'application' version = new Date().format("yyyyMMdd") -tasks.build.dependsOn javadoc +tasks.build.dependsOn javadoc, 'jsdoc' tasks.compileJava.dependsOn 'processSource' sourceSets { @@ -85,7 +85,12 @@ applicationDistribution.from(projectDir) { applicationDistribution.from(javadoc.destinationDir) { include '**' - into 'docs' + into 'docs/javadoc' +} + +applicationDistribution.from("${project.buildDir}/docs/jsdoc") { + include '**' + into 'docs/jsdoc' } distTar { @@ -93,7 +98,7 @@ distTar { } installDist { - dependsOn javadoc + dependsOn javadoc, 'jsdoc' finalizedBy 'update' } @@ -161,6 +166,22 @@ task update { } } +task jsdoc(type: Exec) { + def sources = ['modules/core', 'modules/helma', 'modules/jala/code'] + def destination = "${project.buildDir}/docs/jsdoc" + + sources.each { dir -> inputs.dir dir } + outputs.dir destination + + executable 'npx' + args = ['jsdoc', '-d', "$destination"].plus(sources) + + // As of writing jsdoc throws the following error: + // Unable to parse /home/tobi/Projects/helma/current/modules/jala/code/Database.js: Unexpected token, expected "(" (844:10) + // Seems to be related to the `for each` syntax but did not find any further references. + ignoreExitValue true +} + task shell(type: JavaExec) { def rhinoJar = configurations.library.files.find { f -> f.name.startsWith('rhino') diff --git a/modules/core/Array.js b/modules/core/Array.js index 1e523b3f..fbaaf3e9 100644 --- a/modules/core/Array.js +++ b/modules/core/Array.js @@ -17,14 +17,14 @@ /** * @fileoverview Adds useful methods to the JavaScript Array type. *

- * To use this optional module, its repository needs to be added to the + * To use this optional module, its repository needs to be added to the * application, for example by calling app.addRepository('modules/core/Array.js') - * - * @addon */ /** * Check if this array contains a specific value. + * @external + * @memberof {Array} * @param {Object} val the value to check * @return {boolean} true if the value is contained */ @@ -34,6 +34,8 @@ Array.prototype.contains = function(val) { /** * Retrieve the union set of a bunch of arrays + * @external + * @memberof {Array} * @param {Array} array1,... the arrays to unify * @return {Array} the union set */ @@ -54,6 +56,8 @@ Array.union = function() { /** * Retrieve the intersection set of a bunch of arrays + * @external + * @memberof {Array} * @param {Array} array1,... the arrays to intersect * @return {Array} the intersection set */ diff --git a/modules/core/Date.js b/modules/core/Date.js index eadc2b85..6490196c 100644 --- a/modules/core/Date.js +++ b/modules/core/Date.js @@ -17,7 +17,7 @@ /** * @fileoverview Adds useful methods to the JavaScript Date type. *

- * To use this optional module, its repository needs to be added to the + * To use this optional module, its repository needs to be added to the * application, for example by calling app.addRepository('modules/core/Date.js') */ @@ -33,9 +33,11 @@ Date.ISOFORMAT = "yyyy-MM-dd'T'HH:mm:ss'Z'"; /** * Format a Date to a string. - * For details on the format pattern, see - * http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html - * + * For details on the format pattern, see + * http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html * + * @external + * @memberof {Date} + * * @param String Format pattern * @param Object Java Locale Object (optional) * @param Object Java TimeZone Object (optional) @@ -53,19 +55,23 @@ Date.prototype.format = function (format, locale, timezone) { }; -/** +/** * set the date/time to UTC by subtracting * the timezone offset - */ + * @external + * @memberof {Date} + */ Date.prototype.toUtc = function() { this.setMinutes(this.getMinutes() + this.getTimezoneOffset()); }; -/** +/** * set the date/time to local time by adding * the timezone offset - */ + * @external + * @memberof {Date} + */ Date.prototype.toLocalTime = function() { this.setMinutes(this.getMinutes() - this.getTimezoneOffset()); }; @@ -74,6 +80,8 @@ Date.prototype.toLocalTime = function() { /** * returns the difference between this and another * date object in milliseconds + * @external + * @memberof {Date} */ Date.prototype.diff = function(dateObj) { return this.getTime() - dateObj.getTime(); @@ -82,6 +90,8 @@ Date.prototype.diff = function(dateObj) { /** * return the timespan to current date/time or a different Date object + * @external + * @memberof {Date} * @param Object parameter object containing optional properties: * .now = String to use if difference is < 1 minute * .day|days = String to use for single|multiple day(s) @@ -134,6 +144,8 @@ Date.prototype.getTimespan = function(param) { * return the past timespan between this Date object and * the current Date or a different Date object * @see Date.prototype.getTimespan + * @external + * @memberof {Date} */ Date.prototype.getAge = function(param) { var age = this.getTimespan(param); @@ -147,6 +159,8 @@ Date.prototype.getAge = function(param) { * return the future timespan between this Date object and * the current Date or a different Date object * @see Date.prototype.getTimespan + * @external + * @memberof {Date} */ Date.prototype.getExpiry = function(param) { var age = this.getTimespan(param); @@ -158,6 +172,8 @@ Date.prototype.getExpiry = function(param) { /** * checks if a date object equals another date object + * @external + * @memberof {Date} * @param Object Date object to compare * @param Int indicating how far the comparison should go * @return Boolean diff --git a/modules/core/HopObject.js b/modules/core/HopObject.js index 871de378..507177cb 100644 --- a/modules/core/HopObject.js +++ b/modules/core/HopObject.js @@ -17,7 +17,7 @@ /** * @fileoverview Adds useful methods to Helma's built-in HopObject prototype. *

- * To use this optional module, its repository needs to be added to the + * To use this optional module, its repository needs to be added to the * application, for example by calling app.addRepository('modules/core/HopObject.js') */ @@ -27,6 +27,8 @@ app.addRepository("modules/core/String.js"); /** * Iterates over each child node of the HopObject. + * @external + * @memberof {HopObject} * @param {Function} callback The callback function to be * called for each child node. On every call the first * argument of this function is set to the current value @@ -45,6 +47,8 @@ HopObject.prototype.forEach = function(callback) { /** * macro returns the id of a HopObject + * @external + * @memberof {HopObject} */ HopObject.prototype.id_macro = function() { res.write(this._id); @@ -54,6 +58,8 @@ HopObject.prototype.id_macro = function() { /** * macro returns the url for any hopobject + * @external + * @memberof {HopObject} */ HopObject.prototype.href_macro = function(param, action) { res.write(this.href(action || param.action || String.NULLSTR)); @@ -64,6 +70,8 @@ HopObject.prototype.href_macro = function(param, action) { /** * macro rendering a skin or displaying * its source (param.as == "source") + * @external + * @memberof {HopObject} */ HopObject.prototype.skin_macro = function(param, name) { var skinName = name || param.name; @@ -85,6 +93,8 @@ HopObject.prototype.skin_macro = function(param, name) { /** * this macro renders a text depending on * the value of a given property + * @external + * @memberof {HopObject} */ HopObject.prototype.switch_macro = function(param) { if (param.name) { @@ -97,6 +107,8 @@ HopObject.prototype.switch_macro = function(param) { /** * generic macro that loops over the childobjects * and renders a specified skin for each of them + * @external + * @memberof {HopObject} * @param Object providing the following properties: * skin: the skin to render for each item (required) * collection: the collection containing the items @@ -160,7 +172,7 @@ HopObject.prototype.loop_macro = function(param, collection) { /** - * Render the number of child nodes of the HopObject. + * Render the number of child nodes of the HopObject. * Three cases are distinguished which can be customized * by setting param.verbose to "true" and defining the * corresponding field of the param @@ -170,6 +182,8 @@ HopObject.prototype.loop_macro = function(param, collection) { *
  • param.one - exactly one child node
    • *
  • param.many - more than one child node
    • * + * @external + * @memberof {HopObject} * @param {Object} param The default macro parameter * @param {String} name The default name for a child node */ diff --git a/modules/core/Number.js b/modules/core/Number.js index c9318e6e..1f460109 100644 --- a/modules/core/Number.js +++ b/modules/core/Number.js @@ -17,12 +17,14 @@ /** * @fileoverview Adds useful methods to the JavaScript Number type. *

    - * To use this optional module, its repository needs to be added to the + * To use this optional module, its repository needs to be added to the * application, for example by calling app.addRepository('modules/core/Number.js') */ /** * format a Number to a String + * @external + * @memberof {Number} * @param String Format pattern * @param java.util.Locale An optional Locale instance * @return String Number formatted to a String @@ -39,9 +41,11 @@ Number.prototype.format = function(fmt, locale) { }; -/** +/** * return the percentage of a Number * according to a given total Number + * @external + * @memberof {Number} * @param Int Total * @param String Format Pattern * @param java.util.Locale An optional Locale instance @@ -57,6 +61,8 @@ Number.prototype.toPercent = function(total, fmt, locale) { /** * factory to create functions for sorting objects in an array + * @external + * @memberof {Number} * @param String name of the field each object is compared with * @param Number order (ascending or descending) * @return Function ready for use in Array.prototype.sort diff --git a/modules/core/Object.js b/modules/core/Object.js index 41d59477..5c3f0a58 100644 --- a/modules/core/Object.js +++ b/modules/core/Object.js @@ -23,6 +23,8 @@ /** * Copies the properties of this object into a clone. + * @external + * @memberof {Object} * @param {Object} clone The optional target object * @param {Boolean} recursive If true child objects are cloned as well, otherwise * the clone contains references to the child objects @@ -73,6 +75,8 @@ Object.prototype.clone = function(clone, recursive) { /** * reduce an extended object (ie. a HopObject) * to a generic javascript object + * @external + * @memberof {Object} * @param HopObject the HopObject to be reduced * @return Object the resulting generic object */ @@ -90,6 +94,8 @@ Object.prototype.reduce = function(recursive) { /** * print the contents of an object for debugging + * @external + * @memberof {Object} * @param Object the object to dump * @param Boolean recursive flag (if true, dump child objects, too) */ diff --git a/modules/core/String.js b/modules/core/String.js index 62d2c8ef..79dd050c 100644 --- a/modules/core/String.js +++ b/modules/core/String.js @@ -20,10 +20,6 @@ String.APATTERN = /[^a-zA-Z]/; String.NUMPATTERN = /[^0-9]/; String.FILEPATTERN = /[^a-zA-Z0-9-_\. ]/; String.HEXPATTERN = /[^a-fA-F0-9]/; -// Email and URL RegExps contributed by Scott Gonzalez: http://projects.scottsplayground.com/email_address_validation/ -// licensed unter MIT license - http://www.opensource.org/licenses/mit-license.php -String.EMAILPATTERN = /^((([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+(\.([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+)*)|((\x22)((((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(([\x01-\x08\x0b\x0c\x0e-\x1f\x7f]|\x21|[\x23-\x5b]|[\x5d-\x7e]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(\\([\x01-\x09\x0b\x0c\x0d-\x7f]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))))*(((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(\x22)))@((([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.?$/i; -String.URLPATTERN = /^(https?|ftp):\/\/(((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:)*@)?(((\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5]))|((([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.?)(:\d*)?)(\/((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)+(\/(([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)*)*)?)?(\?((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|[\uE000-\uF8FF]|\/|\?)*)?(\#((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|\/|\?)*)?$/i; String.LEFT = -1 String.BALANCE = 0 String.RIGHT = 1 @@ -32,15 +28,24 @@ String.SPACE = " "; String.EMPTY = ""; String.NULL = String.EMPTY; // to be deprecated? +// Email and URL RegExps contributed by Scott Gonzalez: http://projects.scottsplayground.com/email_address_validation/ +// licensed unter MIT license - http://www.opensource.org/licenses/mit-license.php + +String.EMAILPATTERN = /^((([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+(\.([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+)*)|((\x22)((((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(([\x01-\x08\x0b\x0c\x0e-\x1f\x7f]|\x21|[\x23-\x5b]|[\x5d-\x7e]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(\\([\x01-\x09\x0b\x0c\x0d-\x7f]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))))*(((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(\x22)))@((([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.?$/i; + +String.URLPATTERN = /^(https?|ftp):\/\/(((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:)*@)?(((\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5]))|((([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.?)(:\d*)?)(\/((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)+(\/(([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)*)*)?)?(\?((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|[\uE000-\uF8FF]|\/|\?)*)?(\#((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|\/|\?)*)?$/i; + /** * @fileoverview Adds useful methods to the JavaScript String type. *

    - * To use this optional module, its repository needs to be added to the + * To use this optional module, its repository needs to be added to the * application, for example by calling app.addRepository('modules/core/String.js') */ /** * checks if a date format pattern is correct + * @external + * @memberof {String} * @return Boolean true if the pattern is correct */ String.prototype.isDateFormat = function() { @@ -56,6 +61,8 @@ String.prototype.isDateFormat = function() { /** * parse a timestamp into a date object. This is used when users * want to set createtime explicitly when creating/editing stories. + * @external + * @memberof {String} * @param String date format to be applied * @param Object Java TimeZone Object (optional) * @return Object contains the resulting date @@ -81,6 +88,8 @@ String.prototype.toDate = function(format, timezone) { * function checks if the string passed contains any characters that * are forbidden in URLs and tries to create a java.net.URL from it * FIXME: probably deprecated -> helma.Url + * @external + * @memberof {String} * @return Boolean * @see helma.Url.PATTERN */ @@ -92,6 +101,8 @@ String.prototype.isUrl = function() { /** * function checks if the string passed contains any characters * that are forbidden in image- or filenames + * @external + * @memberof {String} * @return Boolean */ String.prototype.isFileName = function() { @@ -102,6 +113,8 @@ String.prototype.isFileName = function() { /** * function cleans the string passed as argument from any characters * that are forbidden or shouldn't be used in filenames + * @external + * @memberof {String} * @return Boolean */ String.prototype.toFileName = function() { @@ -112,7 +125,9 @@ String.prototype.toFileName = function() { /** * function checks a string for a valid color value in hexadecimal format. * it may also contain # as first character - * @returns Boolean false, if string length (without #) > 6 or < 6 or + * @external + * @memberof {String} + * @returns Boolean false, if string length (without #) > 6 or < 6 or * contains any character which is not a valid hex value */ String.prototype.isHexColor = function() { @@ -129,6 +144,8 @@ String.prototype.isHexColor = function() { * converts a string into a hexadecimal color * representation (e.g. "ffcc33"). also knows how to * convert a color string like "rgb (255, 204, 51)". + * @external + * @memberof {String} * @return String the resulting hex color (w/o "#") */ String.prototype.toHexColor = function() { @@ -151,6 +168,8 @@ String.prototype.toHexColor = function() { /** * function returns true if the string contains * only a-z and 0-9 (case insensitive!) + * @external + * @memberof {String} * @return Boolean true in case string is alpha, false otherwise */ String.prototype.isAlphanumeric = function() { @@ -163,6 +182,8 @@ String.prototype.isAlphanumeric = function() { /** * function cleans a string by throwing away all * non-alphanumeric characters + * @external + * @memberof {String} * @return cleaned string */ String.prototype.toAlphanumeric = function() { @@ -173,6 +194,8 @@ String.prototype.toAlphanumeric = function() { /** * function returns true if the string contains * only characters a-z + * @external + * @memberof {String} * @return Boolean true in case string is alpha, false otherwise */ String.prototype.isAlpha = function() { @@ -185,6 +208,8 @@ String.prototype.isAlpha = function() { /** * function returns true if the string contains * only 0-9 + * @external + * @memberof {String} * @return Boolean true in case string is numeric, false otherwise */ String.prototype.isNumeric = function() { @@ -196,6 +221,8 @@ String.prototype.isNumeric = function() { /** * transforms the first n characters of a string to uppercase + * @external + * @memberof {String} * @param Number amount of characters to transform * @return String the resulting string */ @@ -211,6 +238,8 @@ String.prototype.capitalize = function(limit) { /** * transforms the first n characters of each * word in a string to uppercase + * @external + * @memberof {String} * @return String the resulting string */ String.prototype.titleize = function() { @@ -227,6 +256,8 @@ String.prototype.titleize = function() { /** * translates all characters of a string into HTML entities + * @external + * @memberof {String} * @return String translated result */ String.prototype.entitize = function() { @@ -243,10 +274,12 @@ String.prototype.entitize = function() { /** * breaks up a string into two parts called * head and tail at the given position - * don't apply this to HTML, i.e. use stripTags() in advance + * don't apply this to HTML, i.e. use stripTags() in advance + * @external + * @memberof {String} * @param Number number of charactrers or of segments separated by the delimiter * @param String pre-/suffix to be pre-/appended to shortened string - * @param String delimiter + * @param String delimiter * @return Object containing head and tail properties */ String.prototype.embody = function(limit, clipping, delimiter) { @@ -276,6 +309,8 @@ String.prototype.embody = function(limit, clipping, delimiter) { /** * get the head of a string + * @external + * @memberof {String} * @see String.prototype.embody() */ String.prototype.head = function(limit, clipping, delimiter) { @@ -285,6 +320,8 @@ String.prototype.head = function(limit, clipping, delimiter) { /** * get the tail of a string + * @external + * @memberof {String} * @see String.prototype.embody() */ String.prototype.tail = function(limit, clipping, delimiter) { @@ -292,9 +329,12 @@ String.prototype.tail = function(limit, clipping, delimiter) { }; -/* - * set clip method out of compatibility/convenience reason +/** * FIXME: we eventually have to get rid of this one... + * set clip method out of compatibility/convenience reason + * @external + * @memberof {String} + * @deprecated * @see String.prototype.head() */ String.prototype.clip = String.prototype.head; @@ -302,6 +342,8 @@ String.prototype.clip = String.prototype.head; /** * function inserts a string every number of characters + * @external + * @memberof {String} * @param Int number of characters after which insertion should take place * @param String string to be inserted * @param Boolean definitely insert at each interval position @@ -316,7 +358,7 @@ String.prototype.group = function(interval, str, ignoreWhiteSpace) { for (var i=0; i/g, replacement); - return str; + return str; }; /** * function calculates the md5 hash of a string + * @external + * @memberof {String} * @return String md5 hash of the string */ String.prototype.md5 = function() { @@ -352,6 +398,8 @@ String.prototype.md5 = function() { /** * function repeats a string the specified amount of times + * @external + * @memberof {String} * @param Int amount of repetitions * @return String resulting string */ @@ -366,6 +414,8 @@ String.prototype.repeat = function(multiplier) { /** * function returns true if the string starts with * the string passed as argument + * @external + * @memberof {String} * @param String string pattern to search for * @return Boolean true in case it matches the beginning * of the string, false otherwise @@ -381,6 +431,8 @@ String.prototype.startsWith = function(str, offset) { /** * function returns true if the string ends with * the string passed as argument + * @external + * @memberof {String} * @param String string pattern to search for * @return Boolean true in case it matches the end of * the string, false otherwise @@ -393,6 +445,8 @@ String.prototype.endsWith = function(str) { /** * fills a string with another string up to a desired length + * @external + * @memberof {String} * @param String the filling string * @param Number the desired length of the resulting string * @param Number the direction which the string will be padded in: @@ -429,6 +483,8 @@ String.prototype.pad = function(str, len, mode) { /** * function returns true if a string contains the string * passed as argument + * @external + * @memberof {String} * @param String string to search for * @param Int Position to start search * @param Boolean @@ -443,9 +499,11 @@ String.prototype.contains = function(str, fromIndex) { /** * function compares a string with the one passed as argument * using diff + * @external + * @memberof {String} * @param String String to compare against String object value - * @param String Optional regular expression string to use for - * splitting. If not defined, newlines will be used. + * @param String Optional regular expression string to use for + * splitting. If not defined, newlines will be used. * @return Object Array containing one JS object for each line * with the following properties: * .num Line number @@ -502,6 +560,8 @@ String.prototype.diff = function(mod, separator) { /** * remove leading and trailing whitespace + * @external + * @memberof {String} */ String.prototype.trim = function () { var s = new java.lang.String(this); @@ -511,6 +571,8 @@ String.prototype.trim = function () { /** * returns true if the string looks like an e-mail + * @external + * @memberof {String} */ String.prototype.isEmail = function() { return String.EMAILPATTERN.test(this); @@ -519,6 +581,8 @@ String.prototype.isEmail = function() { /** * returns the amount of occurences of one string in another + * @external + * @memberof {String} */ String.prototype.count = function(str) { var count = 0; @@ -533,6 +597,8 @@ String.prototype.count = function(str) { /** * returns the string encoded using the base64 algorithm + * @external + * @memberof {String} */ String.prototype.enbase64 = function() { var bytes = new java.lang.String(this) . getBytes(); @@ -542,6 +608,8 @@ String.prototype.enbase64 = function() { /** * returns the decoded string using the base64 algorithm + * @external + * @memberof {String} */ String.prototype.debase64 = function() { var bytes = new Packages.sun.misc.BASE64Decoder().decodeBuffer(this); @@ -549,7 +617,7 @@ String.prototype.debase64 = function() { }; -// wrapper methods for string-related +// wrapper methods for string-related // global helma functions String.prototype.encode = function() { @@ -574,6 +642,8 @@ String.prototype.stripTags = function() { /** * factory to create functions for sorting objects in an array + * @external + * @memberof {String} * @param String name of the field each object is compared with * @param Number order (ascending or descending) * @return Function ready for use in Array.prototype.sort @@ -603,6 +673,8 @@ String.Sorter.cache = {}; /** * create a string from a bunch of substrings + * @external + * @memberof {String} * @param String one or more strings as arguments * @return String the resulting string */ @@ -616,6 +688,8 @@ String.compose = function() { /** * creates a random string (numbers and chars) + * @external + * @memberof {String} * @param len length of key * @param mode determines which letters to use. null or 0 = all letters; * 1 = skip 0, 1, l and o which can easily be mixed with numbers; @@ -650,6 +724,8 @@ String.random = function(len, mode) { /** * append one string onto another and add some "glue" * if none of the strings is empty or null. + * @external + * @memberof {String} * @param String the first string * @param String the string to be appended onto the first one * @param String the "glue" to be inserted between both strings diff --git a/modules/helma/all.js b/modules/helma/all.js index f8a3cdcf..3b3dfd0e 100644 --- a/modules/helma/all.js +++ b/modules/helma/all.js @@ -14,9 +14,11 @@ * $Date$ */ -// convenience SingleFileRepository to load all the +// convenience SingleFileRepository to load all the // Javascript library files in ./modules/helma +/** @namespace helma */ + app.addRepository('modules/helma/Aspects.js'); app.addRepository('modules/helma/Chart.js'); app.addRepository('modules/helma/Color.js'); diff --git a/modules/jala/code/Form.js b/modules/jala/code/Form.js index 7a8c4e1a..ee980187 100644 --- a/modules/jala/code/Form.js +++ b/modules/jala/code/Form.js @@ -64,7 +64,7 @@ jala.Form = function(name, dataObj) { * @private */ var tracker = undefined; - + /** * Private field containing all components of this form * @type Array @@ -94,7 +94,7 @@ jala.Form = function(name, dataObj) { /** * Sets the data object which is being edited by this form. This object - * is used to get the default values when first printing the form and + * is used to get the default values when first printing the form and * - if no other object is provided - receives the changed values in save. * @param {Object} dataObj The object which is being edited by this form. * @see #save @@ -158,7 +158,7 @@ jala.Form = function(name, dataObj) { }); var tracker = undefined; - + /** * Sets the tracker object this form instance uses for collecting * error messages and parsed values. @@ -360,7 +360,7 @@ jala.Form.CHECKOPTIONS = "checkoptions"; * @type String * @final */ -jala.Form.CONTENTTYPE = "contenttype"; +jala.Form.CONTENTTYPE = "contenttype"; /** * Constant used by require function to define that an image upload @@ -606,7 +606,7 @@ jala.Form.prototype.render = function() { this.renderFormOpen(); res.write("\n"); - + // print optional general error message var errorMessage = this.getErrorMessage(); if (this.hasError() && errorMessage) { @@ -678,8 +678,8 @@ jala.Form.prototype.validate = function(reqData) { }; /** - * Sets the parsed values on an object. By default the internally - * stored tracker and data objects are used, but those may be + * Sets the parsed values on an object. By default the internally + * stored tracker and data objects are used, but those may be * overridden here. * @param {jala.Form.Tracker} tracker (optional) tracker object * holding parsed data from form input. @@ -785,7 +785,7 @@ jala.Form.Component = function Component(name) { if (!name) { throw "jala.Form.Component: missing component name"; } - + /** * The Form this component belongs to * @type jala.Form @@ -798,7 +798,7 @@ jala.Form.Component = function Component(name) { * @type String */ var className; - + /** * Readonly reference to name of component * @type String @@ -806,14 +806,14 @@ jala.Form.Component = function Component(name) { this.name; // for doc purposes only, readonly-access is through the getter function this.__defineGetter__("name", function() { return name; }); - + /** * Readonly reference to instance of jala.Form. * @type jala.Form */ this.form; // for doc purposes only, readonly-access through the getter function this.__defineGetter__("form", function() { return form; }); - + /** * Attaches this component to an instance of jala.Form. * @param {jala.Form} newForm form object @@ -862,7 +862,7 @@ jala.Form.Component = function Component(name) { this.containsFileUpload = function() { return false; }; - + return this; }; @@ -919,7 +919,7 @@ jala.Form.Component.prototype.save = function(destObj, val) { */ jala.Form.Component.Fieldset = function Fieldset(name) { jala.Form.Component.Fieldset.superConstructor.apply(this, arguments); - + /** * Private field containing the components of this fieldset * @type Array @@ -1078,12 +1078,12 @@ jala.Form.Component.Fieldset.prototype.save = function(tracker, destObj) { */ jala.Form.Component.Skin = function Skin(name) { jala.Form.Component.Skin.superConstructor.apply(this, arguments); - + /** * Private field containing the handler object */ var handler = undefined; - + /** * Returns the handler object for the skin. * @type Object @@ -1133,7 +1133,7 @@ jala.Form.Component.Input = function Input(name) { * Private map containing the requirements that need to be met */ var requirements = {}; - + /** * Private map containing messages to use when a requirement is not met */ @@ -1150,7 +1150,7 @@ jala.Form.Component.Input = function Input(name) { * @type String */ var help; - + /** * Sets a requirement for this component. * If function is called without arguments, jala.Form.REQUIRE @@ -1194,7 +1194,7 @@ jala.Form.Component.Input = function Input(name) { messages[key] = msg; return; }; - + /** * Returns a specific message for a config element. * @param {String} key The key of the message as defined by @@ -1585,7 +1585,7 @@ jala.Form.Component.Input.prototype.getControlAttributes = function() { var attr = { id: this.createDomId("control"), name: this.name, - "class": this.getType() + "class": this.getType() }; if (this.getClassName()) { attr["class"] += " " + this.getClassName(); @@ -1605,7 +1605,7 @@ jala.Form.Component.Input.prototype.checkLength = function(reqData) { var require = this.getRequirement(jala.Form.REQUIRE); var minLength = this.getRequirement(jala.Form.MINLENGTH); var maxLength = this.getRequirement(jala.Form.MAXLENGTH); - + if (require && (reqData[this.name] == null || reqData[this.name].trim() == "")) { return this.getMessage(jala.Form.REQUIRE, "Please enter text into this field."); } else if (maxLength && reqData[this.name].length > maxLength) { @@ -1791,7 +1791,7 @@ jala.Form.Component.Textarea = function Textarea(name) { cols = newCols; return; }; - + return this; }; // extend jala.Form.Component.Input @@ -1910,16 +1910,16 @@ jala.Form.Component.Date.prototype.parseValue = function(reqData) { */ jala.Form.Component.Select = function Select(name) { jala.Form.Component.Select.superConstructor.apply(this, arguments); - + var options, firstOption = undefined; - + /** * Returns the option list for this component. */ this.getOptions = function() { return options; }; - + /** * Sets the option list for this component. * The argument may either be an array that will be used as option list, @@ -1930,13 +1930,13 @@ jala.Form.Component.Select = function Select(name) { *
  • Array of objects [ {value:val, display:display}, .. ]
    • *
  • Array of strings [ display, display, .. ] In this case, * the index position of the string will be the value.
    • - * @param {Array Function} newOptions Array or function defining option list. + * @param {Array|Function} newOptions Array or function defining option list. */ this.setOptions = function(newOptions) { options = newOptions; return; }; - + /** * Returns the text that should be displayed if no value is selected. * @type String @@ -1944,7 +1944,7 @@ jala.Form.Component.Select = function Select(name) { this.getFirstOption = function() { return firstOption; }; - + /** * Sets the text that is displayed if no value is selected * @param {String} newFirstOption text to display as first option element. @@ -1953,7 +1953,7 @@ jala.Form.Component.Select = function Select(name) { firstOption = newFirstOption; return; }; - + return this; }; // extend jala.Form.Component.Input @@ -2224,7 +2224,7 @@ jala.Form.Component.File.prototype.checkRequirements = function(reqData) { return this.getMessage(jala.Form.MAXLENGTH, "This file is too big ({0} bytes), maximum allowed size {1} bytes.", reqData[this.name].contentLength, maxLength); } - + var contentType = this.getRequirement(jala.Form.CONTENTTYPE); if (contentType) { var arr = (contentType instanceof Array) ? contentType : [contentType]; @@ -2233,7 +2233,7 @@ jala.Form.Component.File.prototype.checkRequirements = function(reqData) { reqData[this.name].contentType); } } - + return null; }; @@ -2251,7 +2251,6 @@ jala.Form.Component.File.prototype.checkRequirements = function(reqData) { jala.Form.Component.Image = function() {}; /** - * @ignore * FIXME: JSDoc has some sever problems with this class. * It's somehow due to the named method ("Image") that it * always appears as global static object. @@ -2290,22 +2289,22 @@ jala.Form.Component.Image.prototype.checkRequirements = function(reqData) { } catch (imgError) { return this.getMessage("invalid", "This image file can't be processed."); } - + var maxWidth = this.getRequirement(jala.Form.MAXWIDTH); if (maxWidth && helmaImg.getWidth() > maxWidth) { return this.getMessage("maxwidth", "This image is too wide."); } - + var minWidth = this.getRequirement(jala.Form.MINWIDTH); if (minWidth && helmaImg.getWidth() < minWidth) { return this.getMessage("minwidth", "This image is not wide enough."); } - + var maxHeight = this.getRequirement(jala.Form.MAXHEIGHT); if (maxHeight && helmaImg.getHeight() > maxHeight) { return this.getMessage("maxheight", "This image is too tall."); } - + var minHeight = this.getRequirement(jala.Form.MINHEIGHT); if (minHeight && helmaImg.getHeight() < minHeight) { return this.getMessage("minheight", "This image is not tall enough."); @@ -2333,7 +2332,7 @@ jala.Form.Component.Button = function Button(name) { * @type String */ var value; - + /** * Returns the value set for this button. * @returns value @@ -2375,7 +2374,7 @@ jala.Form.Component.Button.prototype.render = function(attr, value, reqData) { this.renderControls(this.getControlAttributes(), this.getValue()); res.write("\n"); - + jala.Form.html.closeTag("div"); res.write("\n"); return; @@ -2426,7 +2425,7 @@ jala.Form.Component.Submit.prototype.renderControls = function(attr, value) { /** - * static default getter function used to return a field + * static default getter function used to return a field * from the data object. * @param {String} name Name of the property. * @type Object @@ -2436,7 +2435,7 @@ jala.Form.propertyGetter = function(name, value) { }; /** - * static default setter function used to change a field + * static default setter function used to change a field * of the data object. * @param {String} name Name of the property. * @param {Object} value New value of the property. diff --git a/modules/jala/code/PodcastWriter.js b/modules/jala/code/PodcastWriter.js index 906215b5..ba7b173a 100644 --- a/modules/jala/code/PodcastWriter.js +++ b/modules/jala/code/PodcastWriter.js @@ -36,7 +36,7 @@ if (!global.jala) { /** * Jala dependencies */ -app.addRepository(getProperty("jala.dir", "modules/jala") + +app.addRepository(getProperty("jala.dir", "modules/jala") + "/code/Rss20Writer.js"); /** @@ -55,11 +55,11 @@ jala.PodcastWriter = function(header) { name: "text" } }; - + var OWNER = { name: "itunes:owner", value: [{ - name: "itunes:name" + name: "itunes:name" }, { name: "itunes:email" }] @@ -103,7 +103,7 @@ jala.PodcastWriter = function(header) { * Add an iTunes Podcast category. * @param {String} name The category's name. * @param {String} subName The (optional) sub-category's name. - * @param {jala.XmlWriter.XmlElement} parent Optional parent + * @param {jala.XmlWriter.XmlElement} parent Optional parent * element to add the category to. */ this.addItunesCategory = function(name, subName, parent) { @@ -125,5 +125,6 @@ jala.PodcastWriter = function(header) { /** A typical XML header as default. - @type String @final */ + @type {String} + @final */ jala.PodcastWriter.XMLHEADER = ''; diff --git a/modules/jala/code/Utilities.js b/modules/jala/code/Utilities.js index 506a34b9..cd6bd706 100644 --- a/modules/jala/code/Utilities.js +++ b/modules/jala/code/Utilities.js @@ -50,7 +50,6 @@ jala.Utilities = function() { * Return a string representation of the utitility class. * @returns [jala.Utilities] * @type String - * @ignore FIXME: JSDoc bug */ jala.Utilities.toString = function() { return "[jala.Utilities]"; @@ -91,7 +90,7 @@ jala.Utilities.prototype.createPassword = function(len, level) { var LETTERSONLY = 0; var WITHNUMBERS = 1; var WITHSPECIALS = 2; - + var vowels = ['a', 'e', 'i', 'o', 'u']; var consonants = ['b', 'c', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'm', 'n', 'p', 'q', 'r', 's', 't', 'v', 'w', 'x', 'y', 'z']; var specials = ['.', '#', '!', '$', '%', '&', '?']; @@ -153,14 +152,14 @@ jala.Utilities.VALUE_ADDED = 1; jala.Utilities.VALUE_MODIFIED = 2; /** - * Returns an array containing the properties that are + * Returns an array containing the properties that are * added, removed or modified in one object compared to another. * @param {Object} obj1 The first of two objects which should be compared * @param {Object} obj2 The second of two objects which should be compared * @returns An Object containing all properties that are added, removed - * or modified in the second object compared to the first. - * Each property contains a status field with an integer value - * which can be checked against the static jala.Utility fields + * or modified in the second object compared to the first. + * Each property contains a status field with an integer value + * which can be checked against the static jala.Utility fields * VALUE_ADDED, VALUE_MODIFIED and VALUE_REMOVED. * @type Object */ @@ -211,7 +210,7 @@ jala.Utilities.prototype.diffObjects = function(obj1, obj2) { }; /** - * Patches an object with a "diff" object created by the + * Patches an object with a "diff" object created by the * {@link #diffObjects} method. * Please mind that this method is recursive, it descends * along the "diff" object structure. diff --git a/modules/jala/code/XmlWriter.js b/modules/jala/code/XmlWriter.js index 4e422748..8b216427 100644 --- a/modules/jala/code/XmlWriter.js +++ b/modules/jala/code/XmlWriter.js @@ -37,7 +37,7 @@ if (!global.jala) { * Construct a new XML writer. * @class This class defines a generic interface to write * arbitrary and validating XML source code. This is done - * by first applying data objects onto template objects, + * by first applying data objects onto template objects, * both in a specified format. Then, the resulting object * tree is transformed into XML. Moreover, template objects * can be extended with other template objects to provide @@ -48,11 +48,10 @@ if (!global.jala) { */ jala.XmlWriter = function(header) { var self = this; - var XMLHEADER = header || + var XMLHEADER = header || ''; var LOCALE = java.util.Locale.ENGLISH; - /** @ignore FIXME: JSDoc bug */ var write = function(str) { return res.write(str); }; @@ -91,11 +90,11 @@ jala.XmlWriter = function(header) { var children = {}; var properties = [ - "name", - "attributes", - "type", - "required", - "format", + "name", + "attributes", + "type", + "required", + "format", "readonly" ]; @@ -131,7 +130,7 @@ jala.XmlWriter = function(header) { XmlElement.toString = function() { return "[XmlElement constructor]"; }; - + /** @ignore */ XmlElement.prototype.setValue = function(element) { if (element.constructor != this.constructor) @@ -179,15 +178,15 @@ jala.XmlWriter = function(header) { if (data && data.attributes) value = data.attributes[attr.name]; if (data && (data.value || data.attributes) && !value && attr.required) { - throw Error('Missing required ' + (attr.type || Object).name + ' attribute "' + + throw Error('Missing required ' + (attr.type || Object).name + ' attribute "' + attr.name + '" in element <' + this.name + '> (' + value + ")"); } if (value && attr.type && attr.type != value.constructor) { - throw Error('Type mismatch in attribute "' + + throw Error('Type mismatch in attribute "' + this.name + ":" + attr.name + '"'); } if (value) { - app.debug("populating attribute " + attr.name + + app.debug("populating attribute " + attr.name + " with " + value.constructor.name + ": " + value.toSource()); } if (!attr.readonly) { @@ -211,7 +210,7 @@ jala.XmlWriter = function(header) { throw Error('Type mismatch in element "' + this.name + '"'); } if (data) { - app.debug("populating element <" + this.name + "> with " + + app.debug("populating element <" + this.name + "> with " + (this.type || Object).name + ": " + data.toSource()); } if (!this.readonly) @@ -288,7 +287,7 @@ jala.XmlWriter = function(header) { }; /** - * Extend a template object. + * Extend a template object. * @param {Object} template The template object. * @param {Object} ext The extension object. * @returns The XML writer. @@ -303,9 +302,9 @@ jala.XmlWriter = function(header) { } return this; }; - + /** - * Add a namespace to this writer. + * Add a namespace to this writer. * @param {String} name The name of the namespace. * @param {String} url The URL string of the namespace. * @returns The XML root element. diff --git a/modules/jala/code/all.js b/modules/jala/code/all.js index 1b7b9564..049f528d 100644 --- a/modules/jala/code/all.js +++ b/modules/jala/code/all.js @@ -29,6 +29,7 @@ // Define the global namespace for Jala modules if (!global.jala) { + /** @namespace jala */ global.jala = {}; } @@ -39,7 +40,7 @@ if (!global.jala) { "BitTorrent", "Date", "DnsClient", - "Captcha", + "Captcha", "Form", "History", "HtmlDocument",