{"id":22717,"date":"2017-07-13T03:16:12","date_gmt":"2017-07-13T03:16:12","guid":{"rendered":"https:\/\/make.wordpress.org\/core\/?post_type=handbook&#038;p=22717"},"modified":"2025-02-20T04:13:35","modified_gmt":"2025-02-20T04:13:35","slug":"js","status":"publish","type":"handbook","link":"https:\/\/make.wordpress.org\/core\/handbook\/docs\/inline\/js\/","title":{"rendered":"JavaScript Docs"},"content":{"rendered":"<p>This initiative follows the <a href=\"https:\/\/developer.wordpress.org\/coding-standards\/inline-documentation-standards\/\">inline docs initiative<\/a> with a specific focus on <span tabindex='0' class='glossary-item-container'>JavaScript<span class='glossary-item-hidden-content'><span class='glossary-item-header'>JavaScript<\/span> <span class='glossary-item-description'>JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user\u2019s browser.\r<a href=\"https:\/\/www.javascript.com\/\">https:\/\/www.javascript.com<\/a><\/span><\/span><\/span>. The goal is to get all JavaScript files in WordPress well documented and make this documentation easily accessible.\u00a0JavaScript development within WordPress <span tabindex='0' class='glossary-item-container'>core<span class='glossary-item-hidden-content'><span class='glossary-item-header'>Core<\/span> <span class='glossary-item-description'>Core is the set of software required to run WordPress. The Core Development Team builds WordPress.<\/span><\/span><\/span> is speeding up fast and becoming more and more prominent given the current core editor and <span tabindex='0' class='glossary-item-container'>REST API<span class='glossary-item-hidden-content'><span class='glossary-item-header'>REST API<\/span> <span class='glossary-item-description'>The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think \u201cphone app\u201d or \u201cwebsite\u201d) can communicate with the data store (think \u201cdatabase\u201d or \u201cfile system\u201d)\r<a href=\"https:\/\/developer.wordpress.org\/rest-api\/\">https:\/\/developer.wordpress.org\/rest-api\/<\/a><\/span><\/span><\/span> focuses. To help these developments progress as smoothly as possible, we need to make sure the existing code is documented well.<\/p>\n<p>If you\u2019re not familiar with what inline documentation is, read our page <a href=\"https:\/\/make.wordpress.org\/core\/handbook\/best-practices\/inline-documentation-standards\/\">on inline documentation standards<\/a>.<\/p>\n<h2>Which <span tabindex='0' class='glossary-item-container'>JS<span class='glossary-item-hidden-content'><span class='glossary-item-header'>JS<\/span> <span class='glossary-item-description'>JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors.<\/span><\/span><\/span> files should be documented?<\/h2>\n<p>There are three pages tracking JS files for documentation:<\/p>\n<ul>\n<li><a href=\"https:\/\/make.wordpress.org\/core\/2018\/01\/31\/js-docs-initiative-add-inline-docs-for-javascript\/\">Unclaimed JS docs files<\/a>: Nobody is working on documenting these files yet. You can claim a file by commenting on the post.<\/li>\n<li><a href=\"https:\/\/make.wordpress.org\/core\/handbook\/docs\/inline\/js\/in-progress-tickets\/\">In progress JS docs file tickets<\/a>: These files have patches with documentation or someone is working on creating a documentation <span tabindex='0' class='glossary-item-container'>patch<span class='glossary-item-hidden-content'><span class='glossary-item-header'>patch<\/span> <span class='glossary-item-description'>A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a <strong>diff<\/strong>. A patch can be <em>applied<\/em> to a codebase for testing.<\/span><\/span><\/span>.<\/li>\n<li><a href=\"https:\/\/make.wordpress.org\/core\/handbook\/docs\/inline\/js\/closed-tickets\/\">Closed JS docs file tickets<\/a>: These files have been documented already.<\/li>\n<\/ul>\n<h2>How to get involved<\/h2>\n<p>Inline documentation is considered to be \u201ctechnical\u201d documentation, so some familiarity with the WordPress codebase will be necessary \u2013 you have to understand the code to write about it.<\/p>\n<ol>\n<li>Familiarize yourself with the <a href=\"https:\/\/make.wordpress.org\/core\/handbook\/best-practices\/inline-documentation-standards\/javascript\/\">JavaScript documentation standard<\/a>, as well as the <a href=\"https:\/\/make.wordpress.org\/core\/handbook\/best-practices\/inline-documentation-standards\/php\/#formatting-guidelines\">formatting guidelines<\/a> and <a href=\"https:\/\/make.wordpress.org\/core\/handbook\/best-practices\/inline-documentation-standards\/javascript\/#documenting-tips\">documenting tips<\/a>.\n<\/li>\n<li>\n<p>Set up a local copy of the developer version of the WordPress codebase using <a href=\"https:\/\/make.wordpress.org\/core\/handbook\/tutorials\/installing-a-local-server\/installing-vvv\/\">Varying Vagrant Vagrants<\/a> (VVV). WordPress is versioning using <span tabindex='0' class='glossary-item-container'>SVN<span class='glossary-item-hidden-content'><span class='glossary-item-header'>SVN<\/span> <span class='glossary-item-description'>Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase.<\/span><\/span><\/span>, but you can also use <span tabindex='0' class='glossary-item-container'>Git<span class='glossary-item-hidden-content'><span class='glossary-item-header'>Git<\/span> <span class='glossary-item-description'>Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system.\r<a href=\"https:\/\/git-scm.com\/\">https:\/\/git-scm.com\/<\/a><\/span><\/span><\/span> (the VVV link for how to do that).<\/p>\n<\/li>\n<li>\n<p>Read <a href=\"https:\/\/make.wordpress.org\/core\/handbook\/working-with-trac\/opening-a-ticket\/\">Opening a Ticket<\/a> to learn how to create a <span tabindex='0' class='glossary-item-container'>Trac<span class='glossary-item-hidden-content'><span class='glossary-item-header'>Trac<\/span> <span class='glossary-item-description'>An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.<\/span><\/span><\/span> <span tabindex='0' class='glossary-item-container'>ticket<span class='glossary-item-hidden-content'><span class='glossary-item-header'>ticket<\/span> <span class='glossary-item-description'>Created for both bug reports and feature development on the bug tracker.<\/span><\/span><\/span>.<\/p>\n<\/li>\n<li>\n<p>Creating patches:<\/p>\n<\/li>\n<\/ol>\n<ul>\n<li><a href=\"https:\/\/make.wordpress.org\/core\/2018\/01\/31\/js-docs-initiative-add-inline-docs-for-javascript\/\">Claim a file\u00a0to start documenting<\/a>.<\/li>\n<li>Always update your local copy of WordPress <span tabindex='0' class='glossary-item-container'>trunk<span class='glossary-item-hidden-content'><span class='glossary-item-header'>trunk<\/span> <span class='glossary-item-description'>A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running \"trunk\", then you are on the latest revision.<\/span><\/span><\/span> before editing the file and creating patches. Use <code>svn up<\/code> or <code>git pull<\/code>, as appropriate.<\/li>\n<li>Generate the patch from the root directory of your WordPress SVN or Git checkout.<\/li>\n<li>It is best to name your patch file with the Trac ticket number you created, such as <strong>12345.patch<\/strong> or <strong>12345.diff<\/strong>. Either file extension is acceptable.<\/li>\n<\/ul>\n<ol>\n<li>How to submit a patch:<\/li>\n<\/ol>\n<ul>\n<li>Create a <a href=\"https:\/\/core.trac.wordpress.org\/newticket\">new ticket<\/a> on Core Trac for the file:\n<ul>\n<li>Suggested <em>Title<\/em> formats could be \u201cJSDoc correction for path\/to\/file.js\u201d or \u201cImprove documentation for path\/to\/file.js\u201d.<\/li>\n<li>The <em>Type<\/em> should be <strong>defect (<span tabindex='0' class='glossary-item-container'>bug<span class='glossary-item-hidden-content'><span class='glossary-item-header'>bug<\/span> <span class='glossary-item-description'>A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.<\/span><\/span><\/span>)<\/strong>.<\/li>\n<li>Assign the ticket to the <em>Component<\/em> the file is associated with.<\/li>\n<li>Leave the <em>Version<\/em> blank.<\/li>\n<li>Add the <strong>docs<\/strong>\u00a0and the <strong>JavaScript<\/strong>\u00a0<em>Focus<\/em> by clicking on it.<\/li>\n<li>Here\u2019s a shortcut link to create a new ticket in the <code>Media<\/code> component with the <code>docs<\/code> and <code>javascript<\/code> focuses and the title <code>JSDocs correction for<\/code>, all that is left to add is the filename in the title: <a href=\"https:\/\/core.trac.wordpress.org\/newticket?component=Media&amp;focuses=docs%20javascript&amp;summary=JSDocs%20correction%20for%20\">New JSDocs Ticket<\/a><\/li>\n<\/ul>\n<\/li>\n<li>Upload your patch to the Trac ticket you created, and add the keyword <strong>has-patch<\/strong>.<\/li>\n<li>Make sure to leave a comment describing your newly-uploaded patch. Simply uploading patches doesn\u2019t trigger a notification for anyone watching the ticket.<\/li>\n<li>Note: Documentation changes should not mix with code changes (even whitespacing) unless the ticket specifically calls for both.<\/li>\n<\/ul>\n<ol>\n<li>You can also contribute to <a href=\"https:\/\/core.trac.wordpress.org\/query?status=!closed&amp;focuses=~docs\">inline docs-related Trac tickets<\/a> that need iteration.<\/li>\n<\/ol>\n<ul>\n<li>If a ticket is marked <strong>needs-patch<\/strong> or <strong>needs-refresh<\/strong>, it\u2019s possible the existing patch(es) might just need a touch-up or be refreshed against the latest trunk. Every little bit helps!<\/li>\n<\/ul>\n<h2>Points of contact<\/h2>\n<p>For any questions, pop by the <a href=\"https:\/\/wordpress.slack.com\/messages\/docs\/\">#docs<\/a> channel in <a href=\"https:\/\/make.wordpress.org\/chat\/\">Slack<\/a>. For JavaScript specific questions, you can also join the <a href=\"https:\/\/wordpress.slack.com\/messages\/core-js\/\">#core-js<\/a> channel.<\/p>\n<h2>Resources<\/h2>\n<ul>\n<li><a href=\"https:\/\/make.wordpress.org\/core\/handbook\/best-practices\/inline-documentation-standards\/javascript\/\">JS Documentation Standard<\/a><\/li>\n<\/ul>\n<nav class='o2-post-footer-actions'><ul class='o2-post-footer-action-row'><\/ul><div class='o2-post-footer-action-likes'><\/div><ul class='o2-post-footer-action-row'><\/ul><\/nav>","protected":false},"author":5851951,"featured_media":0,"parent":22715,"menu_order":0,"template":"","meta":{"_crdt_document":"","advanced_seo_description":"","jetpack_seo_html_title":"","jetpack_seo_noindex":false,"jetpack_post_was_ever_published":false,"footnotes":""},"class_list":["post-22717","handbook","type-handbook","status-publish","hentry","author-drewapicture","make-js"],"revision_note":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/handbook\/22717","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/handbook"}],"about":[{"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/types\/handbook"}],"author":[{"embeddable":true,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/users\/5851951"}],"version-history":[{"count":8,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/handbook\/22717\/revisions"}],"predecessor-version":[{"id":117121,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/handbook\/22717\/revisions\/117121"}],"up":[{"embeddable":true,"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/handbook\/22715"}],"wp:attachment":[{"href":"https:\/\/make.wordpress.org\/core\/wp-json\/wp\/v2\/media?parent=22717"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}