Commit Graph

12 Commits

Author SHA1 Message Date
whyisjake
3dd9628aae Build/Test Tools: Enable JSDocs to be linted with ESLint.
As part of the [Javascript Inline Docs Initiative](https://make.wordpress.org/core/handbook/docs/inline/js/) this add some tooling to lint Javascript docblocks. Two new commands:

* `npm run lint:jsdoc`
* `npm run lint:jsdoc:fix`

The latter will run the linter and try to fix an possible issues automatically.

Fixes #43828.
Props netweb, atimmer, kamataryo, whyisjake.


Built from https://develop.svn.wordpress.org/trunk@48650


git-svn-id: http://core.svn.wordpress.org/trunk@48412 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-07-27 23:35:02 +00:00
Sergey Biryukov
001ffe81fb Docs: Improve inline comments per the documentation standards.
Includes minor code layout fixes for better readability.

See #48303.
Built from https://develop.svn.wordpress.org/trunk@47122


git-svn-id: http://core.svn.wordpress.org/trunk@46922 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-01-29 00:45:18 +00:00
Sergey Biryukov
2a0489ec49 Docs: Replace @returns tags in JS docs with @return.
Per the documentation standards, `@returns` is an unsupported synonym, `@return` should be used instead:
https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/

See #48303.
Built from https://develop.svn.wordpress.org/trunk@46800


git-svn-id: http://core.svn.wordpress.org/trunk@46600 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2019-11-29 18:01:03 +00:00
Sergey Biryukov
316fa4aecb Code Editor: Check for correct mode value in wp.codeEditor.initialize to enable autocomplete support for PHP.
Props ediamin.
Fixes #47769.
Built from https://develop.svn.wordpress.org/trunk@45670


git-svn-id: http://core.svn.wordpress.org/trunk@45481 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2019-07-25 01:27:57 +00:00
atimmer
bde558be2f Docs: Add file doc @output annotations.
These annotations make it clear to the reader of a JavaScript source
where the build process outputs to. These annotations can later be
integrated in a webpack configuration. This way there is one source of
truth.

The `build` folder is omitted from the paths, because a single JS file
shouldn't not be responsible of knowing where outputs in general will
end up at. A file only knows its output location relative to the
project.

Props adamsilverstein, herregroen, omarreiss, pento.
Fixes #44361.

Built from https://develop.svn.wordpress.org/trunk@43347


git-svn-id: http://core.svn.wordpress.org/trunk@43175 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2018-06-28 02:30:15 +00:00
atimmer
1f707de9dd Docs: Improve wp-admin JSDoc structural data globally.
JSDoc takes it structural data from `@namespace`, `@lends` and `@memberOf`. This change fixes these tags for all JavaScript files in the wp-admin folder.

* Add jsdoc configuration to parse wp-admin/js files. Use `jsdoc -c jsdoc.conf.json` to generate JSDoc.
* Define all used namespaces using `@namespace`.
* Define each usage of the extend function as a prototype assignment using `@lends`.
* Add `@alias` if JSDoc cannot detect the correct name automatically.

This has previously been corrected for all `wp-includes` JavaScript files: [41351].

Props herregroen.
Fixes #42485.

Built from https://develop.svn.wordpress.org/trunk@42403


git-svn-id: http://core.svn.wordpress.org/trunk@42232 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-12-15 13:42:46 +00:00
Weston Ruter
226263bfec Code Editor: Define default gutters and toggle lint markers based on changes to lint option.
Explicitly define `gutters` in base `defaultSettings` to improve merges of multiple calls to `wp_enqueue_code_editor()`.

Props westonruter, georgestephanis for testing.
Amends [41974].
See #12423.

Built from https://develop.svn.wordpress.org/trunk@41992


git-svn-id: http://core.svn.wordpress.org/trunk@41826 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-10-24 16:35:54 +00:00
Weston Ruter
0343b1a2c8 Code Editor: Keep linting and its error reporting configured when lint option is changed dynamically.
Also explicitly disable `lint` option for SCSS and LESS.

See #12423.

Built from https://develop.svn.wordpress.org/trunk@41974


git-svn-id: http://core.svn.wordpress.org/trunk@41808 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-10-23 19:55:46 +00:00
Weston Ruter
d44acf01dc Code Editor: Remove keeping track of wp.codeEditor instances since unused and no removal of instances upon deletion, leading to memory leak.
See #12423.

Built from https://develop.svn.wordpress.org/trunk@41852


git-svn-id: http://core.svn.wordpress.org/trunk@41686 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-10-13 04:34:52 +00:00
Weston Ruter
c8eb741afd Code Editor: Remove scrollIntoView of editor's cursor line upon focus to prevent jumping issues for editor scroll position.
See #41850, #41879.

Built from https://develop.svn.wordpress.org/trunk@41385


git-svn-id: http://core.svn.wordpress.org/trunk@41218 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-09-17 03:58:44 +00:00
Weston Ruter
e5b3921ca4 Code Editor: Scroll the cursor line into view instead of the entire editor when focused.
See #41850.
Fixes #41879.

Built from https://develop.svn.wordpress.org/trunk@41384


git-svn-id: http://core.svn.wordpress.org/trunk@41217 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-09-17 03:35:47 +00:00
Weston Ruter
90bedf8f9d Editor: Add CodeMirror-powered code editor with syntax highlighting, linting, and auto-completion.
* Code editor is integrated into the Theme/Plugin Editor, Additional CSS in Customizer, and Custom HTML widget. Code editor is not yet integrated into the post editor, and it may not be until accessibility concerns are addressed.
* The CodeMirror component in the Custom HTML widget is integrated in a similar way to TinyMCE being integrated into the Text widget, adopting the same approach for integrating dynamic JavaScript-initialized fields.
* Linting is performed for JS, CSS, HTML, and JSON via JSHint, CSSLint, HTMLHint, and JSONLint respectively. Linting is not yet supported for PHP.
* When user lacks `unfiltered_html` the capability, the Custom HTML widget will report any Kses-invalid elements and attributes as errors via a custom Kses rule for HTMLHint.
* When linting errors are detected, the user will be prevented from saving the code until the errors are fixed, reducing instances of broken websites.
* The placeholder value is removed from Custom CSS in favor of a fleshed-out section description which now auto-expands when the CSS field is empty. See #39892.
* The CodeMirror library is included as `wp.CodeMirror` to prevent conflicts with any existing `CodeMirror` global.
* An `wp.codeEditor.initialize()` API in JS is provided to convert a `textarea` into CodeMirror, with a `wp_enqueue_code_editor()` function in PHP to manage enqueueing the assets and settings needed to edit a given type of code.
* A user preference is added to manage whether or not "syntax highlighting" is enabled. The feature is opt-out, being enabled by default.
* Allowed file extensions in the theme and plugin editors have been updated to include formats which CodeMirror has modes for: `conf`, `css`, `diff`, `patch`, `html`, `htm`, `http`, `js`, `json`, `jsx`, `less`, `md`, `php`, `phtml`, `php3`, `php4`, `php5`, `php7`, `phps`, `scss`, `sass`, `sh`, `bash`, `sql`, `svg`, `xml`, `yml`, `yaml`, `txt`.

Props westonruter, georgestephanis, obenland, melchoyce, pixolin, mizejewski, michelleweber, afercia, grahamarmfield, samikeijonen, rianrietveld, iseulde.
See #38707.
Fixes #12423, #39892.

Built from https://develop.svn.wordpress.org/trunk@41376


git-svn-id: http://core.svn.wordpress.org/trunk@41209 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2017-09-13 06:08:47 +00:00