diff --git a/docs/API-Reference/language/CSSUtils.md b/docs/API-Reference/language/CSSUtils.md index 07eb92bd75..df76ffeb94 100644 --- a/docs/API-Reference/language/CSSUtils.md +++ b/docs/API-Reference/language/CSSUtils.md @@ -9,6 +9,30 @@ const CSSUtils = brackets.getModule("language/CSSUtils") Set of utilities for simple parsing of CSS text. **Kind**: global variable + + +## SELECTOR : string +CSS selector, used to target specific elements + +**Kind**: global constant + + +## PROP\_NAME : string +name of the property + +**Kind**: global constant + + +## PROP\_VALUE : string +value of the specified property + +**Kind**: global constant + + +## IMPORT\_URL : string +url for import + +**Kind**: global constant ## isCSSPreprocessorFile(filePath) ⇒ boolean @@ -189,6 +213,17 @@ selector(s) for the first rule. | --- | --- | --- | | range | TextRange | The range to extract the selector(s) from. | + + +## getAllCssSelectorsInProject(options) +Responsible to get all the CSS selectors in project + +**Kind**: global function + +| Param | Type | +| --- | --- | +| options | Object | + ## SelectorInfo : Object diff --git a/docs/API-Reference/language/HTMLSimpleDOM.md b/docs/API-Reference/language/HTMLSimpleDOM.md new file mode 100644 index 0000000000..c28aa4879d --- /dev/null +++ b/docs/API-Reference/language/HTMLSimpleDOM.md @@ -0,0 +1,135 @@ +### Import : +```js +const HTMLSimpleDOM = brackets.getModule("language/HTMLSimpleDOM") +``` + + + +## SimpleNode +**Kind**: global class + +* [SimpleNode](#SimpleNode) + * [new SimpleNode(properties)](#new_SimpleNode_new) + * [.update()](#SimpleNode+update) + * [.updateAttributeSignature()](#SimpleNode+updateAttributeSignature) + * [.isElement()](#SimpleNode+isElement) ⇒ bool + * [.isText()](#SimpleNode+isText) ⇒ bool + + + +### new SimpleNode(properties) +A SimpleNode represents one node in a SimpleDOM tree. Each node can have +any set of properties on it, though there are a couple of assumptions made. +Elements will have `children` and `attributes` properties. Text nodes will have a `content` +property. All Elements will have a `tagID` and text nodes *can* have one. + + +| Param | Type | Description | +| --- | --- | --- | +| properties | Object | the properties provided will be set on the new object. | + + + +### simpleNode.update() +Updates signatures used to optimize the number of comparisons done during +diffing. This is important to call if you change: + +* children +* child node attributes +* text content of a text node +* child node text + +**Kind**: instance method of [SimpleNode](#SimpleNode) + + +### simpleNode.updateAttributeSignature() +Updates the signature of this node's attributes. Call this after making attribute changes. + +**Kind**: instance method of [SimpleNode](#SimpleNode) + + +### simpleNode.isElement() ⇒ bool +Is this node an element node? + +**Kind**: instance method of [SimpleNode](#SimpleNode) +**Returns**: bool - true if it is an element + + +### simpleNode.isText() ⇒ bool +Is this node a text node? + +**Kind**: instance method of [SimpleNode](#SimpleNode) +**Returns**: bool - true if it is text + + +## Builder +**Kind**: global class + +* [Builder](#Builder) + * [new Builder(text, startOffset, startOffsetPos)](#new_Builder_new) + * [.getID](#Builder+getID) ⇒ int + * [.build(strict, markCache)](#Builder+build) ⇒ [SimpleNode](#SimpleNode) + * [.getNewID()](#Builder+getNewID) ⇒ int + + + +### new Builder(text, startOffset, startOffsetPos) +A Builder creates a SimpleDOM tree of SimpleNode objects representing the +"important" contents of an HTML document. It does not include things like comments. +The nodes include information about their position in the text provided. + + +| Param | Type | Description | +| --- | --- | --- | +| text | string | The text to parse | +| startOffset | int | starting offset in the text | +| startOffsetPos | Object | line/ch position in the text | + + + +### builder.getID ⇒ int +Returns the best tag ID for the new tag object given. +The default implementation just calls `getNewID` +and returns a unique ID. + +**Kind**: instance property of [Builder](#Builder) +**Returns**: int - unique tag ID + +| Param | Type | Description | +| --- | --- | --- | +| newTag | Object | tag object to potentially inspect to choose an ID | + + + +### builder.build(strict, markCache) ⇒ [SimpleNode](#SimpleNode) +Builds the SimpleDOM. + +**Kind**: instance method of [Builder](#Builder) +**Returns**: [SimpleNode](#SimpleNode) - root of tree or null if parsing failed + +| Param | Type | Description | +| --- | --- | --- | +| strict | bool | if errors are detected, halt and return null | +| markCache | Object | a cache that can be used in ID generation (is passed to `getID`) | + + + +### builder.getNewID() ⇒ int +Returns a new tag ID. + +**Kind**: instance method of [Builder](#Builder) +**Returns**: int - unique tag ID + + +## build(text, strict) ⇒ [SimpleNode](#SimpleNode) +Builds a SimpleDOM from the text provided. If `strict` mode is true, parsing +will halt as soon as any error is seen and null will be returned. + +**Kind**: global function +**Returns**: [SimpleNode](#SimpleNode) - root of tree or null if strict failed + +| Param | Type | Description | +| --- | --- | --- | +| text | string | Text of document to parse | +| strict | bool | True for strict parsing | + diff --git a/docs/API-Reference/language/LanguageManager.md b/docs/API-Reference/language/LanguageManager.md index bc47d9b77c..04ed0f51bc 100644 --- a/docs/API-Reference/language/LanguageManager.md +++ b/docs/API-Reference/language/LanguageManager.md @@ -3,14 +3,211 @@ const LanguageManager = brackets.getModule("language/LanguageManager") ``` + + +## Language +**Kind**: global class + +* [Language](#Language) + * [new Language()](#new_Language_new) + * [.getId()](#Language+getId) ⇒ string + * [.getName()](#Language+getName) ⇒ string + * [.getMode()](#Language+getMode) ⇒ string + * [.getFileExtensions()](#Language+getFileExtensions) ⇒ Array.<string> + * [.getFileNames()](#Language+getFileNames) ⇒ Array.<string> + * [.addFileExtension(extension)](#Language+addFileExtension) + * [.removeFileExtension(extension)](#Language+removeFileExtension) + * [.addFileName(extension)](#Language+addFileName) + * [.removeFileName(extension)](#Language+removeFileName) + * [.hasLineCommentSyntax()](#Language+hasLineCommentSyntax) ⇒ boolean + * [.getLineCommentPrefixes()](#Language+getLineCommentPrefixes) ⇒ Array.<string> + * [.setLineCommentSyntax(prefix)](#Language+setLineCommentSyntax) ⇒ boolean + * [.hasBlockCommentSyntax()](#Language+hasBlockCommentSyntax) ⇒ boolean + * [.getBlockCommentPrefix()](#Language+getBlockCommentPrefix) ⇒ string + * [.getBlockCommentSuffix()](#Language+getBlockCommentSuffix) ⇒ string + * [.setBlockCommentSyntax(prefix, suffix)](#Language+setBlockCommentSyntax) ⇒ boolean + * [.getLanguageForMode(mode)](#Language+getLanguageForMode) ⇒ [Language](#Language) + * [.isFallbackLanguage()](#Language+isFallbackLanguage) ⇒ boolean + * [.isBinary()](#Language+isBinary) ⇒ boolean + + + +### new Language() +Model for a language. + + + +### language.getId() ⇒ string +Returns the identifier for this language. + +**Kind**: instance method of [Language](#Language) +**Returns**: string - The identifier + + +### language.getName() ⇒ string +Returns the human-readable name of this language. + +**Kind**: instance method of [Language](#Language) +**Returns**: string - The name + + +### language.getMode() ⇒ string +Returns the CodeMirror mode for this language. + +**Kind**: instance method of [Language](#Language) +**Returns**: string - The mode + + +### language.getFileExtensions() ⇒ Array.<string> +Returns an array of file extensions for this language. + +**Kind**: instance method of [Language](#Language) +**Returns**: Array.<string> - File extensions used by this language + + +### language.getFileNames() ⇒ Array.<string> +Returns an array of file names for extensionless files that use this language. + +**Kind**: instance method of [Language](#Language) +**Returns**: Array.<string> - Extensionless file names used by this language + + +### language.addFileExtension(extension) +Adds one or more file extensions to this language. + +**Kind**: instance method of [Language](#Language) + +| Param | Type | Description | +| --- | --- | --- | +| extension | string \| Array.<string> | A file extension (or array thereof) used by this language | + + + +### language.removeFileExtension(extension) +Unregisters one or more file extensions from this language. + +**Kind**: instance method of [Language](#Language) + +| Param | Type | Description | +| --- | --- | --- | +| extension | string \| Array.<string> | File extension (or array thereof) to stop using for this language | + + + +### language.addFileName(extension) +Adds one or more file names to the language which is used to match files that don't have extensions like "Makefile" for example. + +**Kind**: instance method of [Language](#Language) + +| Param | Type | Description | +| --- | --- | --- | +| extension | string \| Array.<string> | An extensionless file name (or array thereof) used by this language | + + + +### language.removeFileName(extension) +Unregisters one or more file names from this language. + +**Kind**: instance method of [Language](#Language) + +| Param | Type | Description | +| --- | --- | --- | +| extension | string \| Array.<string> | An extensionless file name (or array thereof) used by this language | + + + +### language.hasLineCommentSyntax() ⇒ boolean +Returns whether the line comment syntax is defined for this language. + +**Kind**: instance method of [Language](#Language) +**Returns**: boolean - Whether line comments are supported + + +### language.getLineCommentPrefixes() ⇒ Array.<string> +Returns an array of prefixes to use for line comments. + +**Kind**: instance method of [Language](#Language) +**Returns**: Array.<string> - The prefixes + + +### language.setLineCommentSyntax(prefix) ⇒ boolean +Sets the prefixes to use for line comments in this language or prints an error to the console. + +**Kind**: instance method of [Language](#Language) +**Returns**: boolean - Whether the syntax was valid and set or not + +| Param | Type | Description | +| --- | --- | --- | +| prefix | string \| Array.<string> | Prefix string or an array of prefix strings to use for line comments (e.g. "//" or ["//", "#"]) | + + + +### language.hasBlockCommentSyntax() ⇒ boolean +Returns whether the block comment syntax is defined for this language. + +**Kind**: instance method of [Language](#Language) +**Returns**: boolean - Whether block comments are supported + + +### language.getBlockCommentPrefix() ⇒ string +Returns the prefix to use for block comments. + +**Kind**: instance method of [Language](#Language) +**Returns**: string - The prefix + + +### language.getBlockCommentSuffix() ⇒ string +Returns the suffix to use for block comments. + +**Kind**: instance method of [Language](#Language) +**Returns**: string - The suffix + + +### language.setBlockCommentSyntax(prefix, suffix) ⇒ boolean +Sets the prefix and suffix to use for blocks comments in this language or prints an error to the console. + +**Kind**: instance method of [Language](#Language) +**Returns**: boolean - Whether the syntax was valid and set or not + +| Param | Type | Description | +| --- | --- | --- | +| prefix | string | Prefix string to use for block comments (e.g. "< !--") | +| suffix | string | Suffix string to use for block comments (e.g. "-->") | + + + +### language.getLanguageForMode(mode) ⇒ [Language](#Language) +Returns either a language associated with the mode or the fallback language. +Used to disambiguate modes used by multiple languages. + +**Kind**: instance method of [Language](#Language) +**Returns**: [Language](#Language) - This language if it uses the mode, or whatever [#_getLanguageForMode](#_getLanguageForMode) returns + +| Param | Type | Description | +| --- | --- | --- | +| mode | string | The mode to associate the language with | + + + +### language.isFallbackLanguage() ⇒ boolean +Determines whether this is the fallback language or not + +**Kind**: instance method of [Language](#Language) +**Returns**: boolean - True if this is the fallback language, false otherwise + + +### language.isBinary() ⇒ boolean +Indicates whether or not the language is binary (e.g., image or audio). + +**Kind**: instance method of [Language](#Language) -## getLanguage(id) ⇒ [Language](#new_Language_new) +## getLanguage(id) ⇒ [Language](#Language) Resolves a language ID to a Language object. File names have a higher priority than file extensions. **Kind**: global function -**Returns**: [Language](#new_Language_new) - The language with the provided identifier or undefined +**Returns**: [Language](#Language) - The language with the provided identifier or undefined | Param | Type | Description | | --- | --- | --- | @@ -18,13 +215,13 @@ File names have a higher priority than file extensions. -## getLanguageForExtension(extension) ⇒ [Language](#new_Language_new) +## getLanguageForExtension(extension) ⇒ [Language](#Language) Resolves a file extension to a Language object. *Warning:* it is almost always better to use getLanguageForPath(), since Language can depend on file name and even full path. Use this API only if no relevant file/path exists. **Kind**: global function -**Returns**: [Language](#new_Language_new) - The language for the provided extension or null if none exists +**Returns**: [Language](#Language) - The language for the provided extension or null if none exists | Param | Type | Description | | --- | --- | --- | @@ -32,11 +229,11 @@ on file name and even full path. Use this API only if no relevant file/path exis -## getLanguageForPath(path, [ignoreOverride]) ⇒ [Language](#new_Language_new) +## getLanguageForPath(path, [ignoreOverride]) ⇒ [Language](#Language) Resolves a file path to a Language object. **Kind**: global function -**Returns**: [Language](#new_Language_new) - The language for the provided file type or the fallback language +**Returns**: [Language](#Language) - The language for the provided file type or the fallback language | Param | Type | Description | | --- | --- | --- | diff --git a/src/language/CSSUtils.js b/src/language/CSSUtils.js index 1be7851a30..99e7067206 100644 --- a/src/language/CSSUtils.js +++ b/src/language/CSSUtils.js @@ -43,11 +43,38 @@ define(function (require, exports, module) { _ = require("thirdparty/lodash"); const MAX_CONTENT_LENGTH = 10 * 1024 * 1024; // 10MB - // Constants - const SELECTOR = "selector", - PROP_NAME = "prop.name", - PROP_VALUE = "prop.value", - IMPORT_URL = "import.url"; + + /** + * CSS selector, used to target specific elements + * + * @type {string} + * @constant + */ + const SELECTOR = "selector"; + + /** + * name of the property + * + * @type {string} + * @constant + */ + const PROP_NAME = "prop.name"; + + /** + * value of the specified property + * + * @type {string} + * @constant + */ + const PROP_VALUE = "prop.value"; + + /** + * url for import + * + * @type {string} + * @constant + */ + const IMPORT_URL = "import.url"; /** * List of all bracket pairs that is keyed by opening brackets, and the inverted list @@ -2062,6 +2089,12 @@ define(function (require, exports, module) { } let globalPrecacheRun = 0; + + /** + * Responsible to get all the CSS selectors in project + * + * @param {Object} options + */ function getAllCssSelectorsInProject(options = { includeClasses: true, includeIDs: true, diff --git a/src/language/HTMLSimpleDOM.js b/src/language/HTMLSimpleDOM.js index ed86518103..694a0e52d5 100644 --- a/src/language/HTMLSimpleDOM.js +++ b/src/language/HTMLSimpleDOM.js @@ -19,6 +19,8 @@ * */ +// @INCLUDE_IN_API_DOCS + /*unittests: HTML Instrumentation*/ define(function (require, exports, module) { @@ -37,6 +39,8 @@ define(function (require, exports, module) { * tags to close. This mostly comes from the HTML5 spec section on omitted close tags: * http://www.w3.org/html/wg/drafts/html/master/syntax.html#optional-tags * This doesn't handle general content model violations. + * + * @private */ var openImpliesClose = { li: { li: true }, @@ -92,6 +96,8 @@ define(function (require, exports, module) { /** * A list of elements which are automatically closed when their parent is closed: * http://www.w3.org/html/wg/drafts/html/master/syntax.html#optional-tags + * + * @private */ var optionalClose = { html: true, @@ -120,6 +126,8 @@ define(function (require, exports, module) { /** * A list of tags that are self-closing (do not contain other elements). * Mostly taken from http://www.w3.org/html/wg/drafts/html/master/syntax.html#void-elements + * + * @private */ var voidElements = { area: true, diff --git a/src/language/LanguageManager.js b/src/language/LanguageManager.js index 65e264bd85..c5ed872cb2 100644 --- a/src/language/LanguageManager.js +++ b/src/language/LanguageManager.js @@ -442,7 +442,6 @@ define(function (require, exports, module) { /** * Model for a language. - * @private * @constructor */ function Language() { @@ -518,7 +517,6 @@ define(function (require, exports, module) { /** * Returns the identifier for this language. - * @private * @return {string} The identifier */ Language.prototype.getId = function () { @@ -548,7 +546,6 @@ define(function (require, exports, module) { /** * Returns the human-readable name of this language. - * @private * @return {string} The name */ Language.prototype.getName = function () { @@ -572,7 +569,6 @@ define(function (require, exports, module) { /** * Returns the CodeMirror mode for this language. - * @private * @return {string} The mode */ Language.prototype.getMode = function () { @@ -641,7 +637,6 @@ define(function (require, exports, module) { /** * Returns an array of file extensions for this language. - * @private * @return {Array.} File extensions used by this language */ Language.prototype.getFileExtensions = function () { @@ -651,7 +646,6 @@ define(function (require, exports, module) { /** * Returns an array of file names for extensionless files that use this language. - * @private * @return {Array.} Extensionless file names used by this language */ Language.prototype.getFileNames = function () { @@ -661,7 +655,6 @@ define(function (require, exports, module) { /** * Adds one or more file extensions to this language. - * @private * @param {!string|Array.} extension A file extension (or array thereof) used by this language */ Language.prototype.addFileExtension = function (extension) { @@ -701,7 +694,6 @@ define(function (require, exports, module) { /** * Unregisters one or more file extensions from this language. - * @private * @param {!string|Array.} extension File extension (or array thereof) to stop using for this language */ Language.prototype.removeFileExtension = function (extension) { @@ -732,7 +724,6 @@ define(function (require, exports, module) { /** * Adds one or more file names to the language which is used to match files that don't have extensions like "Makefile" for example. - * @private * @param {!string|Array.} extension An extensionless file name (or array thereof) used by this language */ Language.prototype.addFileName = function (name) { @@ -762,7 +753,6 @@ define(function (require, exports, module) { /** * Unregisters one or more file names from this language. - * @private * @param {!string|Array.} extension An extensionless file name (or array thereof) used by this language */ Language.prototype.removeFileName = function (name) { @@ -788,7 +778,6 @@ define(function (require, exports, module) { /** * Returns whether the line comment syntax is defined for this language. - * @private * @return {boolean} Whether line comments are supported */ Language.prototype.hasLineCommentSyntax = function () { @@ -797,7 +786,6 @@ define(function (require, exports, module) { /** * Returns an array of prefixes to use for line comments. - * @private * @return {Array.} The prefixes */ Language.prototype.getLineCommentPrefixes = function () { @@ -806,7 +794,6 @@ define(function (require, exports, module) { /** * Sets the prefixes to use for line comments in this language or prints an error to the console. - * @private * @param {!(string|Array.)} prefix Prefix string or an array of prefix strings * to use for line comments (e.g. "//" or ["//", "#"]) * @return {boolean} Whether the syntax was valid and set or not @@ -832,7 +819,6 @@ define(function (require, exports, module) { /** * Returns whether the block comment syntax is defined for this language. - * @private * @return {boolean} Whether block comments are supported */ Language.prototype.hasBlockCommentSyntax = function () { @@ -841,7 +827,6 @@ define(function (require, exports, module) { /** * Returns the prefix to use for block comments. - * @private * @return {string} The prefix */ Language.prototype.getBlockCommentPrefix = function () { @@ -850,7 +835,6 @@ define(function (require, exports, module) { /** * Returns the suffix to use for block comments. - * @private * @return {string} The suffix */ Language.prototype.getBlockCommentSuffix = function () { @@ -859,7 +843,6 @@ define(function (require, exports, module) { /** * Sets the prefix and suffix to use for blocks comments in this language or prints an error to the console. - * @private * @param {!string} prefix Prefix string to use for block comments (e.g. "< !--") * @param {!string} suffix Suffix string to use for block comments (e.g. "-->") * @return {boolean} Whether the syntax was valid and set or not @@ -878,7 +861,6 @@ define(function (require, exports, module) { /** * Returns either a language associated with the mode or the fallback language. * Used to disambiguate modes used by multiple languages. - * @private * @param {!string} mode The mode to associate the language with * @return {Language} This language if it uses the mode, or whatever {@link #_getLanguageForMode} returns */ @@ -912,7 +894,6 @@ define(function (require, exports, module) { /** * Determines whether this is the fallback language or not - * @private * @return {boolean} True if this is the fallback language, false otherwise */ Language.prototype.isFallbackLanguage = function () { @@ -923,7 +904,6 @@ define(function (require, exports, module) { * Trigger the "languageModified" event if this language is registered already * @private * @see #_triggerLanguageModified - * @private */ Language.prototype._wasModified = function () { if (_languages[this._id]) { @@ -933,7 +913,6 @@ define(function (require, exports, module) { /** * Indicates whether or not the language is binary (e.g., image or audio). - * @private * @return {boolean} */ Language.prototype.isBinary = function () {