archive-gh-me/jsdoc
1
0
Fork 0
mirror of https://github.com/jsdoc/jsdoc.git synced 2025-12-08 19:46:11 +00:00
Code Issues Projects Releases Wiki Activity

draft 3.3.0 changelog

Browse Source
This commit is contained in:
Jeff Williams 2014-12-27 09:39:45 -08:00
parent 6faad35eb5
commit 8c4c98d101
1 changed files with 87 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
changes.md
View File

@ -2,6 +2,87 @@
This file describes notable changes in each version of JSDoc 3. To download a specific version of JSDoc 3, see [GitHub's tags page](https://github.com/jsdoc3/jsdoc/tags).
## 3.3.0 (January 2015)
**Note**: This draft changelog is current through December 27, 2014, and is subject to change before JSDoc 3.3.0 is released.
### Major changes
+ You can now run JSDoc on Node.js. (#93)
+ You can now use the `@interface` and `@implements` tags to document interfaces and their implementations. (#720, #828)
+ Closure Compiler's `@inheritDoc` and `@override` tags are now supported. (#53)
+ If the JSDoc comment for a symbol includes the `@mixes` tag, all of the mixins now appear in the symbol's documentation. (#378)
+ JSDoc can now log information to the console as it runs (for example, the name of each file that JSDoc parses). To log this information, run JSDoc with the `--verbose` flag. (#416)
+ You can now use any file as the package or README file for your documentation. Use the `-P/--package/` and `-R/--readme` flags to specify the package and README file. (#708)
+ The default template's typography and color scheme have been significantly improved. (#550, #780, #843)
### Enhancements
+ You can now use the `--pedantic` flag to treat all errors as fatal errors, and to treat warnings as errors. This flag replaces the `--lenient` flag, which had roughly the opposite meaning and is no longer available. (#416)
+ You can now use the `--debug` flag to log detailed debugging information to the console. This information can help you diagnose bugs in JSDoc itself. (#416)
+ JSDoc's configuration file can now contain JavaScript comments. (#660)
+ You can now include source files from a directory, but exclude one of its subdirectories, by adding the subdirectory to the `source.exclude` option in the configuration file. (#484)
+ The `source.exclude` option now works correctly when JSDoc is run with the `-r/--recurse` flag. (#616)
+ When JSDoc is run with the `-r/--recurse` flag, it now scans for tutorials recursively. (#712)
+ JSDoc's `-X/--explain` option now runs much more quickly. (#633)
+ If all of the text for an `@example` tag is indented, JSDoc now removes the extra indentation. (#540)
+ The default value for a parameter or property can now include brackets (for example, `@param {Array.<string>} [foo=['bar']]`). (#640)
+ You can now provide a default value for parameters and properties that are not optional (for example, `@property {string} foo='bar'`). (#791)
+ If the `@type` tag includes a description (for example, `@type {string} some text`), JSDoc now parses the type expression correctly and discards the description. (#615)
+ You can now add JSDoc comments to function parameters. (#473)
+ For Closure Compiler projects, you can now enable a Closure Compiler-specific tag dictionary that more closely matches Closure Compiler's semantics. To enable Closure Compiler semantics, set the configuration file's `tags.dictionaries` option to `['closure']`. This option can contain the values `jsdoc`, `closure`, or both. If multiple dictionaries are enabled, and a tag is defined in more than one dictionary, JSDoc uses the definition from the first dictionary that contains the tag. (#729, #730, #731, #732)
+ If one symbol overrides another, JSDoc now adds an `overrides` property to the doclet that is overriding another. The `overrides` property contains the longname of the overridden symbol. (#792)
+ When a JSDoc tag contains a type expression, the doclet's `type` object now includes a hidden `parsedType` property. The `parsedType` property contains a syntax tree that represents the type expression. The syntax tree is generated by [Catharsis](https://github.com/hegemonic/catharsis), and its format may change in the future. (#576)
+ JSDoc now allows output filenames to contain non-ASCII characters. In addition, links to output files are now URL-encoded when necessary. (#677)
+ JSDoc now ensures that output filenames do not have a leading underscore. (#758)
+ JSDoc now tries to ensure that `id` attributes in output files are unique within that file. (#539)
+ JSDoc now has an up-to-date JSON Schema file for parse results. The schema file is available in `lib/jsdoc/schema.js`. (#327)
+ JSDoc now extracts more information from package files. (#710)
+ JSDoc now displays usage information if you run JSDoc without any input files, or with an unrecognized command-line option. (#609, #840)
### Bug fixes
+ When the `allowUnknownTags` option is set to `false`, JSDoc no longer logs warnings about the presence of `@also` and `@scope` tags. (#574)
+ Fixed several errors when parsing type expressions. (#619, #644, #652, #705, #767)
+ Properties added to the `module.exports` object can now be documented. (#500)
+ When a symbol's name starts with the same characters as its parent namespace (such as `Vector` in `V.Vector`), JSDoc now assigns the correct longname to the symbol. (#608)
+ If a child class inherits from multiple parent classes, and the parent classes have instance members with the same name, the child class no longer displays the documentation from both parent classes. (#613)
+ If a source file contains an object literal, and one of the property names is a whitespace character or a character that must be escaped in a regular expression, JSDoc now parses the file successfully. (#549, #775)
+ Virtual comments now work correctly for overloaded functions. (#727)
+ When a virtual comment appears within a module, JSDoc now assigns the correct values to the virtual comment doclet's `memberof`, `longname`, and `scope` properties. (#631)
+ JSDoc now sets the `scope` property to `global` for all global doclets. (#684)
+ Module doclets no longer have a `scope` property. (#782)
+ In Markdown tutorials, JSDoc no longer unescapes HTML entities. (#743)
+ When a single JSDoc comment includes `@class`, `@classdesc`, and `@constructor` tags, JSDoc no longer ignores the value of the `@classdesc` tag. (#806)
+ For tags where the name and type are both optional (`@constant`, `@external`, `@member`, `@module`, `@namespace`, and `@param`), JSDoc now parses the tag correctly when it includes a type but not a name. (#351, #535)
+ The `@default` tag now works correctly when used with an array literal. (#604)
+ The `@enum` tag now works correctly when the enumeration is part of a chain of assignments (for example, `var FOO = exports.FOO = {/* enumerated values */}`). (#702)
+ The `@exports` and `@module` tags now work correctly when their value includes a `module:` namespace (for example, `@exports module:foo`). (#786)
+ The `@variation` tag now works correctly when its value is enclosed in parentheses (for example, `@variation (foo)`). (#850)
### Plugins
+ Tag definitions can now have a `mustNotHaveDescription` property. When this property is set to `true`, JSDoc will warn the user if the tag text includes a description (such as `The description` in `@param {string} foo - The description`). (#615)
+ The Markdown plugin no longer prevents inline `{@link}` tags from working. (#518)
+ The Markdown plugin now converts `exceptions` properties to HTML by default. (#736)
+ JSDoc now includes a `summarize` plugin that automatically generates summaries based on the description. (#485)
+ Plugins can now replace the `doclet` property of `newDoclet` events. (#584)
### Template improvements
+ You can now override the default template's main layout file, `layout.tmpl`, by setting the `templates.default.layoutFile` option in JSDoc's configuration file. The property can contain a relative or absolute path to the replacement for `layout.tmpl`. Relative paths are resolved against the path to the configuration file; the current working directory; and the JSDoc directory, in that order. (#480)
+ When the `templates.default.outputSourceFiles` option is set to `false`, the documentation no longer shows the path to each source file. (#571)
+ You can now use the property `templates.default.staticFiles.include` to list files that will be copied to the output directory. For backwards compatibility, the property `templates.default.staticFiles.paths` is also supported but is deprecated. (#785)
+ The `templates.default.staticFiles` options now work correctly on Windows. (#785)
+ Output files no longer show the default value for members of an enumeration. (#689)
+ If a constructor is assigned to `module.exports`, the value of the `@classdesc` tag now appears in the documentation. (#740)
+ If a constructor is assigned to `module.exports`, and the constructor inherits from another class, the parent class is now listed in the documentation. (#594)
+ Text within an `@example` tag, including HTML tags, is now properly escaped. (#511)
+ If a member has a `@fires` tag, the tag information now appears in the documentation. (#568)
+ If a symbol has members that use the `@mixin` tag, the mixins are now listed in the documentation. (#379, #602)
+ If a member has a `@requires` tag, the tag information now appears in the documentation. (#563)
+ Type expressions are now presented more clearly. (#618)
+ Pretty-printed source files now include line numbers. (#532)
+ When you run JSDoc with a single input file, the full path to the file no longer appears in the documentation. (#553)
+ When an overloaded function is assigned to `module.exports`, the documentation now displays all of the signatures for the overloaded function. (#727)
+ Resolved several issues that caused the default template to generate invalid HTML. (#843)
## 3.2.2 (November 2013)
### Bug fixes
@ -12,6 +93,7 @@ This file describes notable changes in each version of JSDoc 3. To download a sp
+ If a function accepts a parameter named `prototype`, the parameter is no longer renamed during parsing. (#505)
+ If the list of input files includes relative paths, the paths are now resolved relative to the user's working directory. (a3d33842)
## 3.2.1 (October 2013)
### Enhancements
@ -43,6 +125,7 @@ This file describes notable changes in each version of JSDoc 3. To download a sp
+ If a `@default` tag is added to a symbol whose default value is an object, the value is now displayed in the output file. (#419)
+ Output files now identify symbols as "abstract" rather than "virtual." (#432)
## 3.2.0 (May 2013)
### Major changes
@ -101,6 +184,7 @@ This file describes notable changes in each version of JSDoc 3. To download a sp
+ The "Classes" header is no longer repeated in the navigation bar. (#361)
+ When the only documented symbols in global scope are type definitions, you can now click the "Global" header to view their documentation. (#261)
## 3.1.1 (February 2013)
+ Resolved a crash when no input files contain JSDoc comments. (#329)
@ -114,6 +198,7 @@ This file describes notable changes in each version of JSDoc 3. To download a sp
+ `getSignatureTypes`
+ `linkto`
## 3.1.0 (January 2013)
### Major changes
@ -218,6 +303,7 @@ This file describes notable changes in each version of JSDoc 3. To download a sp
+ Members are now contained in arrays rather than objects, allowing overloaded members to be documented. (#153)
+ A clearer error message is now provided when the output destination is not specified correctly. (#174)
## 3.0.1 (June 2012)
### Enhancements
@ -235,6 +321,7 @@ This file describes notable changes in each version of JSDoc 3. To download a sp
+ The default template now sorts classes by name correctly when the classes come from several modules. (4ce17195)
+ The Haruki template now correctly supports `@example`, `@members`, and `@returns` tags. (6580e176, 59655252, 31c8554d)
## 3.0.0 (May 2012)
Initial release.