Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

doc: More cleanup and normalization of PDoc source

  • Loading branch information...
commit b737737d9c3ed5048318cf8b1ca557b23785f803 1 parent 67124eb
@dandean dandean authored samleb committed
Showing with 47 additions and 45 deletions.
  1. +5 −5 src/lang/number.js
  2. +37 −35 src/lang/string.js
  3. +5 −5 src/lang/template.js
View
10 src/lang/number.js
@@ -20,7 +20,7 @@ Object.extend(Number.prototype, (function() {
* (which is therefore assumed to be in the \[0..255\] range, inclusive).
* Useful for composing CSS color strings.
*
- * <h5>Example</h5>
+ * ##### Example
*
* 10.toColorPart()
* // -> "0a"
@@ -32,8 +32,8 @@ Object.extend(Number.prototype, (function() {
/**
* Number#succ() -> Number
*
- * Returns the successor of the current Number, as defined by current + 1.
- * Used to make numbers compatible with ObjectRange.
+ * Returns the successor of the current [[Number]], as defined by current + 1.
+ * Used to make numbers compatible with [[ObjectRange]].
**/
function succ() {
return this + 1;
@@ -49,7 +49,7 @@ Object.extend(Number.prototype, (function() {
* the first parameter. The number will be 0 on first call, 1 on second
* call, etc. `times` returns the number instance it was called on.
*
- * <h5>Example</h5>
+ * ##### Example
*
* (3).times(alert);
* // -> Alerts "0", then "1", then "2"; returns 3
@@ -81,7 +81,7 @@ Object.extend(Number.prototype, (function() {
* that the string's length is at least equal to `length`. Takes an optional
* `radix` argument which specifies the base to use for conversion.
*
- * <h5>Examples</h5>
+ * ##### Examples
*
* (13).toPaddedString(4);
* // -> "0013"
View
72 src/lang/string.js
@@ -3,7 +3,7 @@
*
* Extensions to the built-in `String` class.
*
- * Prototype enhances the `String` object with a series of useful methods for
+ * Prototype enhances the [[String]] object with a series of useful methods for
* ranging from the trivial to the complex. Tired of stripping trailing
* whitespace? Try [[String#strip]]. Want to replace `replace`? Have a look at
* [[String#sub]] and [[String#gsub]]. Need to parse a query string? We have
@@ -243,23 +243,24 @@ Object.extend(String.prototype, (function() {
*
* Strips a string of any HTML tags.
*
- * Note that `stripTags` will only strip HTML 4.01 tags &mdash; like `div`,
- * `span`, and `abbr`. It _will not_ strip namespace-prefixed tags such
- * as `h:table` or `xsl:template`.
+ * Note that [[String#stripTags]] will only strip HTML 4.01 tags &mdash; like
+ * `div`, `span`, and `abbr`. It _will not_ strip namespace-prefixed tags
+ * such as `h:table` or `xsl:template`.
*
- * Watch out for `<script>` tags in your string, as `String#stripTags` will _not_ remove
- * their content. Use [[String#stripScripts]] to do so.
+ * Watch out for `<script>` tags in your string, as [[String#stripTags]] will
+ * _not_ remove their content. Use [[String#stripScripts]] to do so.
*
- * <h5>Caveat User</h5>
+ * ##### Caveat User
*
- * Note that the processing `stripTags` does is good enough for most purposes, but
- * you cannot rely on it for security purposes. If you're processing end-user-supplied
- * content, `stripTags` is _not_ sufficiently robust to ensure that the content
- * is completely devoid of HTML tags in the case of a user intentionally trying to circumvent
- * tag restrictions. But then, you'll be running them through [[String#escapeHTML]] anyway,
- * won't you?
+ * Note that the processing [[String#stripTags]] does is good enough for most
+ * purposes, but you cannot rely on it for security purposes. If you're
+ * processing end-user-supplied content, [[String#stripTags]] is _not_
+ * sufficiently robust to ensure that the content is completely devoid of
+ * HTML tags in the case of a user intentionally trying to circumvent tag
+ * restrictions. But then, you'll be running them through
+ * [[String#escapeHTML]] anyway, won't you?
*
- * <h5>Examples</h5>
+ * ##### Examples
*
* 'a <a href="#">link</a>'.stripTags();
* // -> 'a link'
@@ -286,10 +287,10 @@ Object.extend(String.prototype, (function() {
*
* ##### Caveat User
*
- * Note that the processing `stripScripts` does is good enough for most purposes,
- * but you cannot rely on it for security purposes. If you're processing
- * end-user-supplied content, `stripScripts` is probably not sufficiently robust
- * to prevent hack attacks.
+ * Note that the processing [[String#stripScripts]] does is good enough for
+ * most purposes, but you cannot rely on it for security purposes. If you're
+ * processing end-user-supplied content, [[String#stripScripts]] is probably
+ * not sufficiently robust to prevent hack attacks.
**/
function stripScripts() {
return this.replace(new RegExp(Prototype.ScriptFragment, 'img'), '');
@@ -298,13 +299,12 @@ Object.extend(String.prototype, (function() {
/**
* String#extractScripts() -> Array
*
- * Extracts the content of any `script` blocks present in the string and
+ * Extracts the content of any `<script>` blocks present in the string and
* returns them as an array of strings.
*
- * This method is used internally by [[String#evalScripts]].
- * It does _not_ evaluate the scripts (use [[String#evalScripts]]
- * to do that), but can be usefull if you need to evaluate the scripts at a
- * later date.
+ * This method is used internally by [[String#evalScripts]]. It does _not_
+ * evaluate the scripts (use [[String#evalScripts]] to do that), but can be
+ * usefull if you need to evaluate the scripts at a later date.
*
* ##### Examples
*
@@ -341,7 +341,7 @@ Object.extend(String.prototype, (function() {
* Returns an array containing the value returned by each script.
* `<script>` blocks referencing external files will be treated as though
* they were empty (the result for that position in the array will be `undefined`);
- * external files are _not_ loaded and processed by `evalScripts`.
+ * external files are _not_ loaded and processed by [[String#evalScripts]].
*
* ##### Examples
*
@@ -353,15 +353,16 @@ Object.extend(String.prototype, (function() {
*
* ##### About `evalScripts`, `var`s, and defining functions
*
- * `evalScripts` evaluates script blocks, but this **does not** mean they are
- * evaluated in the global scope. They aren't, they're evaluated in the scope of
- * the `evalScripts` method. This has important ramifications for your scripts:
+ * [[String#evalScripts]] evaluates script blocks, but this **does not** mean
+ * they are evaluated in the global scope. They aren't, they're evaluated in
+ * the scope of the [[String#evalScripts]] method. This has important
+ * ramifications for your scripts:
*
* * Anything in your script declared with the `var` keyword will be
* discarded momentarily after evaluation, and will be invisible to any
* other scope.
- * * If any `<script>` blocks _define functions_, they will need to be assigned to
- * properties of the `window` object.
+ * * If any `<script>` blocks _define functions_, they will need to be
+ * assigned to properties of the `window` object.
*
* For example, this won't work:
*
@@ -378,8 +379,8 @@ Object.extend(String.prototype, (function() {
* }
*
* (You can leave off the `window.` part of that, but it's bad form.)
- * Evaluates the content of any `script` block present in the string. Returns an array
- * containing the value returned by each script.
+ * Evaluates the content of any `script` block present in the string. Returns
+ * an array containing the value returned by each script.
**/
function evalScripts() {
return this.extractScripts().map(function(script) { return eval(script) });
@@ -436,7 +437,7 @@ Object.extend(String.prototype, (function() {
* the hash symbol (`"#"`), and runs `decodeURIComponent()` on each
* parameter/value pair.
*
- * `String#toQueryParams` also aggregates the values of identical keys into
+ * [[String#toQueryParams]] also aggregates the values of identical keys into
* an array of values.
*
* Note that parameters which do not have a specified value will be set to
@@ -489,7 +490,7 @@ Object.extend(String.prototype, (function() {
* Splits the string character-by-character and returns an array with
* the result.
*
- * <h5>Examples</h5>
+ * ##### Examples
*
* 'a'.toArray();
* // -> ['a']
@@ -505,6 +506,7 @@ Object.extend(String.prototype, (function() {
* String#succ() -> String
*
* Used internally by ObjectRange.
+ *
* Converts the last character of the string to the following character in
* the Unicode alphabet.
*
@@ -819,8 +821,8 @@ Object.extend(String.prototype, (function() {
/**
* String#blank() -> Boolean
*
- * Check if the string is "blank" &mdash; either empty (length of `0`) or containing
- * only whitespace.
+ * Check if the string is "blank" &mdash; either empty (length of `0`) or
+ * containing only whitespace.
*
* ##### Example
*
View
10 src/lang/template.js
@@ -11,12 +11,12 @@
*
* There's nothing wrong with this approach, except that it is hard to
* visualize the output immediately just by glancing at the concatenation
- * expression. The `Template` class provides a much nicer and clearer way of
+ * expression. The [[Template]] class provides a much nicer and clearer way of
* achieving this formatting.
*
* ##### Straightforward templates
*
- * The `Template` class uses a basic formatting syntax, similar to what is
+ * The [[Template]] class uses a basic formatting syntax, similar to what is
* used in Ruby. The templates are created from strings that have embedded
* symbols in the form (e.g., `#{fieldName}`) that will be replaced by
* actual values when the template is applied (evaluated) to an object.
@@ -38,7 +38,7 @@
*
* ##### Templates are meant to be reused
*
- * As the example illustrates, `Template` objects are not tied to specific
+ * As the example illustrates, [[Template]] objects are not tied to specific
* data. The data is bound to the template only during the evaluation of the
* template, without affecting the template itself. The next example shows the
* same template being used with a handful of distinct objects.
@@ -64,7 +64,7 @@
*
* There's always the chance that one day you'll need to have a literal in your
* template that looks like a symbol, but is not supposed to be replaced. For
- * these situations there's an escape character: the backslash (<code>\\</code>).
+ * these situations there's an escape character: the backslash (`\\`).
*
* // NOTE: you're seeing two backslashes here because the backslash
* // is also an escape character in JavaScript strings, so a literal
@@ -79,7 +79,7 @@
*
* The default syntax of the template strings will probably be enough for most
* scenarios. In the rare occasion where the default Ruby-like syntax is
- * inadequate, there's a provision for customization. `Template`'s
+ * inadequate, there's a provision for customization. [[Template]]'s
* constructor accepts an optional second argument that is a regular expression
* object to match the replaceable symbols in the template string. Let's put
* together a template that uses a syntax similar to the now ubiquitous `{{ }}`
Please sign in to comment.
Something went wrong with that request. Please try again.