Jump to content
 







Main menu
   


Navigation  



Main page
Contents
Current events
Random article
About Wikipedia
Contact us
Donate
 




Contribute  



Help
Learn to edit
Community portal
Recent changes
Upload file
 








Search  

































Create account

Log in
 









Create account
 Log in
 




Pages for logged out editors learn more  



Contributions
Talk
 



















Contents

   



(Top)
 


1 History  





2 JSDoc tags  





3 Example  





4 JSDoc in use  





5 See also  





6 References  





7 External links  














JSDoc






العربية
Español
فارسی
Français


Русский
Српски / srpski
Türkçe
Українська
 

Edit links
 









Article
Talk
 

















Read
Edit
View history
 








Tools
   


Actions  



Read
Edit
View history
 




General  



What links here
Related changes
Upload file
Special pages
Permanent link
Page information
Cite this page
Get shortened URL
Download QR code
Wikidata item
 




Print/export  



Download as PDF
Printable version
 
















Appearance
   

 






From Wikipedia, the free encyclopedia
 


Initial release1999; 25 years ago (1999)
Latest release

3.6.3
15 July 2019; 4 years ago (2019-07-15)

Type of formatProgramming documentation Format
Contained byJavaScript source files
Extended fromJavaDoc
Open format?Yes
Websitejsdoc.app

JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating. This is then processed, by various tools, to produce documentation in accessible formats like HTML and Rich Text Format. The JSDoc specification is released under CC BY-SA 3.0, while its companion documentation generator and parser library is free software under the Apache License 2.0.

History[edit]

JSDoc's syntax and semantics are similar to those of the Javadoc scheme, which is used for documenting code written in Java. JSDoc differs from Javadoc, in that it is specialized to handle JavaScript's dynamic behaviour.[1]

An early example using a Javadoc-like syntax to document JavaScript was released in 1999 with the Netscape/Mozilla project Rhino, a JavaScript run-time system written in Java. It included a toy "JSDoc" HTML generator, versioned up to 1.3, as an example of its JavaScript capabilities.[2]

All main generations of "JSDoc" were headed by micmath (Michael Mathews). He started with JSDoc.pm in 2001, a simple system written in Perl. Later, with contributions by Canadian programmer Gabriel Reid. It was hosted on SourceForge in a CVS repository.[3] By JSDoc 1.0 (2007) he rewrote the system in JavaScript (again for Rhino), and after a set of expansions JSDoc 2.0 (2008) gained the name "jsdoc-toolkit". Released under the MIT License, it was hosted in a Subversion repositoryonGoogle Code.[4] By 2011 he has refactored the system into JSDoc 3.0 and hosted the result on GitHub. It now runs on Node.js.[1]

JSDoc tags[edit]

Some of the more popular annotation tags used in modern JSDoc are:

Tag Description
@author Developer's name
@constructor Marks a function as a constructor
@deprecated Marks a method as deprecated
@exception Synonym for @throws
@exports Identifies a member that is exported by the module
@param Documents a method parameter; a datatype indicator can be added between curly braces
@private Signifies that a member is private
@returns Documents a return value
@return Synonym for @returns
@see Documents an association to another object
@todo Documents something that is missing/open
@this Specifies the type of the object to which the keyword this refers within a function.
@throws Documents an exception thrown by a method
@version Provides the version number of a library

Example[edit]

/** @class Circle representing a circle. */
class Circle {
  /**
   * Creates an instance of Circle.
   *
   * @author: moi
   * @param {number} r The desired radius of the circle.
   */
  constructor(r) {
    /** @private */ this.radius = r
    /** @private */ this.circumference = 2 * Math.PI * r
  }

  /**
   * Creates a new Circle from a diameter.
   *
   * @param {number} d The desired diameter of the circle.
   * @return {Circle} The new Circle object.
   */
  static fromDiameter(d) {
    return new Circle(d / 2)
  }

  /**
   * Calculates the circumference of the Circle.
   *
   * @deprecated since 1.1.0; use getCircumference instead
   * @return {number} The circumference of the circle.
   */
  calculateCircumference() {
    return 2 * Math.PI * this.radius
  }

  /**
   * Returns the pre-computed circumference of the Circle.
   *
   * @return {number} The circumference of the circle.
   * @since 1.1.0
   */
  getCircumference() {
    return this.circumference
  }

  /**
   * Find a String representation of the Circle.
   *
   * @override
   * @return {string} Human-readable representation of this Circle.
   */
  toString() {
    return `[A Circle object with radius of ${this.radius}.]`
  }
}

/**
 * Prints a circle.
 *
 * @param {Circle} circle
 */
function printCircle(circle) {
    /** @this {Circle} */
    function bound() { console.log(this) }
    bound.apply(circle)
}

Note that the @class and @constructor tags can in fact be omitted: the ECMASyntax is sufficient to make their identities clear, and JSDoc makes use of that.[5] @override can be automatically deduced as well.[6]

JSDoc in use[edit]

See also[edit]

References[edit]

  1. ^ a b "JSDoc". GitHub. jsdoc. 4 September 2019. Retrieved 4 September 2019.
  • ^ "Rhino example: jsdoc.js". GitHub. Mozilla project. May 6, 1999.
  • ^ "JSDoc". SourceForge. Git conversion
  • ^ "jsdoc-toolkit". Google Code. Git conversion
  • ^ "ES 2015 Classes". Use JSDoc.
  • ^ "@override". Use JSDoc.
  • ^ "Type Checking JavaScript Files". TypeScript Documentation.
  • External links[edit]


    Retrieved from "https://en.wikipedia.org/w/index.php?title=JSDoc&oldid=1222494134"

    Categories: 
    Free documentation generators
    Source code documentation formats
    JavaScript programming tools
    Hidden categories: 
    Articles with short description
    Short description matches Wikidata
    Articles needing additional references from January 2013
    All articles needing additional references
    Webarchive template wayback links
    Official website different in Wikidata and Wikipedia
     



    This page was last edited on 6 May 2024, at 07:54 (UTC).

    Text is available under the Creative Commons Attribution-ShareAlike License 4.0; additional terms may apply. By using this site, you agree to the Terms of Use and Privacy Policy. Wikipedia® is a registered trademark of the Wikimedia Foundation, Inc., a non-profit organization.



    Privacy policy

    About Wikipedia

    Disclaimers

    Contact Wikipedia

    Code of Conduct

    Developers

    Statistics

    Cookie statement

    Mobile view



    Wikimedia Foundation
    Powered by MediaWiki