Merge pull request #1850 from vikaskaliramna07/main

Improved documentation & types

lib/comment.d.ts

@@ -31,17 +31,19 @@ declare namespace Comment {
 }
 
 /**
- * Represents a comment between declarations or statements (rule and at-rules).
+ * It represents a class that handles
+ * [CSS comments](https://developer.mozilla.org/en-US/docs/Web/CSS/Comments)
  *
  * ```js
  * Once (root, { Comment }) {
- *   let note = new Comment({ text: 'Note: …' })
+ *   const note = new Comment({ text: 'Note: …' })
  *   root.append(note)
  * }
  * ```
  *
- * Comments inside selectors, at-rule parameters, or declaration values
- * will be stored in the `raws` properties explained above.
+ * Remember that CSS comments inside selectors, at-rule parameters,
+ * or declaration values will be stored in the `raws` properties
+ * explained above.
  */
 declare class Comment_ extends Node {
   type: 'comment'

lib/declaration.d.ts

@@ -44,20 +44,22 @@ declare namespace Declaration {
 }
 
 /**
- * Represents a CSS declaration.
+ * It represents a class that handles
+ * [CSS declarations](https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax#css_declarations)
  *
  * ```js
  * Once (root, { Declaration }) {
- *   let color = new Declaration({ prop: 'color', value: 'black' })
+ *   const color = new Declaration({ prop: 'color', value: 'black' })
  *   root.append(color)
  * }
  * ```
  *
  * ```js
  * const root = postcss.parse('a { color: black }')
- * const decl = root.first.first
- * decl.type       //=> 'decl'
- * decl.toString() //=> ' color: black'
+ * const decl = root.first?.first
+ *
+ * console.log(decl.type)       //=> 'decl'
+ * console.log(decl.toString()) //=> ' color: black'
  * ```
  */
 declare class Declaration_ extends Node {
@@ -66,57 +68,69 @@ declare class Declaration_ extends Node {
   raws: Declaration.DeclarationRaws
 
   /**
-   * The declaration's property name.
+   * The property name for a CSS declaration.
    *
    * ```js
    * const root = postcss.parse('a { color: black }')
-   * const decl = root.first.first
-   * decl.prop //=> 'color'
+   * const decl = root.first?.first
+   *
+   * console.log(decl.prop) //=> 'color'
    * ```
    */
   prop: string
 
   /**
-   * The declaration’s value.
+   * The property value for a CSS declaration.
    *
-   * This value will be cleaned of comments. If the source value contained
-   * comments, those comments will be available in the `raws` property.
-   * If you have not changed the value, the result of `decl.toString()`
-   * will include the original raws value (comments and all).
+   * Any CSS comments inside the value string will be filtered out.
+   * CSS comments present in the source value will be available in
+   * the `raws` property.
+   *
+   * Assigning new `value` would ignore the comments in `raws`
+   * property while compiling node to string.
    *
    * ```js
    * const root = postcss.parse('a { color: black }')
-   * const decl = root.first.first
-   * decl.value //=> 'black'
+   * const decl = root.first?.first
+   *
+   * console.log(decl.value) //=> 'black'
    * ```
    */
   value: string
 
   /**
-   * `true` if the declaration has an `!important` annotation.
+   * It represents a specificity of the declaration.
+   *
+   * If true, the CSS declaration will have an
+   * [important](https://developer.mozilla.org/en-US/docs/Web/CSS/important)
+   * specifier.
    *
    * ```js
    * const root = postcss.parse('a { color: black !important; color: red }')
-   * root.first.first.important //=> true
-   * root.first.last.important  //=> undefined
+   *
+   * console.log(root.first?.first?.important) //=> true
+   * console.log(root.first?.last?.important)  //=> undefined
    * ```
    */
   important: boolean
 
   /**
-   * `true` if declaration is declaration of CSS Custom Property
-   * or Sass variable.
+   * The `variable` method represents a getter that returns true
+   * if a declaration starts with `--` or `$`, which are used to
+   * declare variables in CSS and SASS/SCSS.
    *
    * ```js
    * const root = postcss.parse(':root { --one: 1 }')
-   * let one = root.first.first
-   * one.variable //=> true
+   * const one = root.first?.first
+   *
+   * console.log(one?.variable) //=> true
    * ```
    *
    * ```js
    * const root = postcss.parse('$one: 1')
-   * let one = root.first
-   * one.variable //=> true
+   * const one = root.first
+   *
+   * console.log(one?.variable) //=> true
    * ```
    */
   variable: boolean

lib/node.d.ts

@@ -80,6 +80,10 @@ declare namespace Node {
     end?: Position
   }
 
+  /**
+   * NodeProps represents an interface for an object received
+   * as parameter by Node class constructor.
+   */
   export interface NodeProps {
     source?: Source
   }
@@ -112,7 +116,7 @@ declare namespace Node {
 }
 
 /**
- * `Node` represents an abstract class that handles common
+ * It represents an abstract class that handles common
  * methods for other CSS abstract syntax tree nodes.
  *
  * Any node that represents CSS selector or value should
@@ -232,15 +236,23 @@ declare abstract class Node_ {
   constructor(defaults?: object)
 
   /**
-   * Returns a `CssSyntaxError` instance containing the original position
-   * of the node in the source, showing line and column numbers and also
-   * a small excerpt to facilitate debugging.
+   * The Node.error method creates an instance of the
+   * class `CssSyntaxError` and parameters passed to
+   * this method are assigned to the error instance.
+   *
+   * The error instance will have description for the
+   * error, original position of the node in the
+   * source, showing line and column number.
+   *
+   * If any previous map is present, it would be used
+   * to get original position of the source.
    *
-   * If present, an input source map will be used to get the original position
-   * of the source, even from a previous compilation step
-   * (e.g., from Sass compilation).
+   * The Previous Map here is referred to the source map
+   * generated by previous compilation, example: Less,
+   * Stylus and Sass.
    *
-   * This method produces very useful error messages.
+   * This method returns the error instance instead of
+   * throwing it.
    *
    * ```js
    * if (!variables[name]) {
@@ -253,51 +265,54 @@ declare abstract class Node_ {
    * }
    * ```
    *
-   * @param message Error description.
-   * @param opts    Options.
+   * @param message Description for the error instance.
+   * @param options Options for the error instance.
    *
-   * @return Error object to throw it.
+   * @return Error instance is returned.
    */
   error(message: string, options?: Node.NodeErrorOptions): CssSyntaxError
 
   /**
-   * This method is provided as a convenience wrapper for `Result#warn`.
+   * The `warn` method is a wrapper for Result#warn,
+   * providing convenient way of generating warnings.
    *
    * ```js
    *   Declaration: {
    *     bad: (decl, { result }) => {
-   *       decl.warn(result, 'Deprecated property bad')
+   *       decl.warn(result, 'Deprecated property: bad')
    *     }
    *   }
    * ```
    *
    * @param result The `Result` instance that will receive the warning.
-   * @param text   Warning message.
-   * @param opts   Warning Options.
+   * @param message Description for the warning.
+   * @param options Options for the warning.
    *
-   * @return Created warning object.
+   * @return `Warning` instance is returned
    */
-  warn(result: Result, text: string, opts?: WarningOptions): Warning
+  warn(result: Result, message: string, options?: WarningOptions): Warning
 
   /**
-   * Removes the node from its parent and cleans the parent properties
-   * from the node and its children.
+   * The `remove` method removes the node from its parent
+   * and deletes its parent property.
    *
    * ```js
    * if (decl.prop.match(/^-webkit-/)) {
    *   decl.remove()
    * }
    * ```
    *
-   * @return Node to make calls chain.
+   * @return `this` for method chaining.
    */
   remove(): this
 
   /**
-   * Returns a CSS string representing the node.
+   * The `toString` method compiles the node to
+   * browser readable cascading style sheets string
+   * depending on it's type.
    *
    * ```js
-   * new Rule({ selector: 'a' }).toString() //=> "a {}"
+   * console.log(new Rule({ selector: 'a' }).toString()) //=> "a {}"
    * ```
    *
    * @param stringifier A syntax to use in string generation.
@@ -306,22 +321,23 @@ declare abstract class Node_ {
   toString(stringifier?: Stringifier | Syntax): string
 
   /**
-   * Assigns properties to the current node.
+   * The `assign` method assigns properties to an existing
+   * node instance.
    *
    * ```js
    * decl.assign({ prop: 'word-wrap', value: 'break-word' })
    * ```
    *
    * @param overrides New properties to override the node.
-   * @return Current node to methods chain.
+   *
+   * @return `this` for method chaining.
    */
   assign(overrides: object): this
 
   /**
-   * Returns an exact clone of the node.
-   *
-   * The resulting cloned node and its (cloned) children will retain
-   * code style properties.
+   * The `clone` method creates clone of an existing node,
+   * which includes all the properties and their values, that
+   * includes `raws` but not `type`.
    *
    * ```js
    * decl.raws.before    //=> "\n  "
@@ -331,9 +347,10 @@ declare abstract class Node_ {
    * ```
    *
    * @param overrides New properties to override in the clone.
-   * @return Clone of the node.
+   *
+   * @return Duplicate of the node instance.
    */
-  clone(overrides?: object): this
+  clone(overrides?: object): Node_
 
   /**
    * Shortcut to clone the node and insert the resulting cloned node
@@ -453,7 +470,7 @@ declare abstract class Node_ {
   root(): Root
 
   /**
-   * Returns a `Node#raws` value. If the node is missing
+   * Returns a `raws` value. If the node is missing
    * the code style property (because the node was manually built or cloned),
    * PostCSS will try to autodetect the code style property by looking
    * at other nodes in the tree.