Skip to content

Commit

Permalink
doc: More cleanup and normalization of PDoc source
Browse files Browse the repository at this point in the history
  • Loading branch information
@samleb
dandean authored and samleb committed Mar 8, 2010
1 parent 67124eb commit b737737
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 45 deletions.
10 changes: 5 additions & 5 deletions src/lang/number.js
View file
Expand Up @@ -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"
Expand All @@ -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;
Expand All @@ -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
Expand Down Expand Up @@ -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"
Expand Down
72 changes: 37 additions & 35 deletions src/lang/string.js
View file
Expand Up @@ -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
Expand Down Expand Up @@ -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'
Expand All @@ -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'), '');
Expand All @@ -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
*
Expand Down Expand Up @@ -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
*
Expand All @@ -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:
*
Expand All @@ -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) });
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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']
Expand All @@ -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.
*
Expand Down Expand Up @@ -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
*
Expand Down
10 changes: 5 additions & 5 deletions src/lang/template.js
View file
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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 `{{ }}`
Expand Down

0 comments on commit b737737

Please sign in to comment.