refactor: add tsdoc comments

- add tsdoc comments with @public and descriptions
- use purgecss UserDefinedOptions to create the plugins's options

docs/configuration.md

@@ -277,8 +277,8 @@ e.g:
 
 ```js
 const purgecss = await new PurgeCSS().purge({
-  content: [], // content
-  css: [], // css
+  content: [],
+  css: [],
   safelist: ['random', 'yep', 'button']
 })
 ```
@@ -287,8 +287,8 @@ In this example, the selectors `.random`, `#yep`, `button` will be left in the f
 
 ```js
 const purgecss = await new PurgeCSS().purge({
-  content: [], // content
-  css: [], // css
+  content: [],
+  css: [],
   safelist: [/red$/]
 })
 ```
@@ -301,8 +301,8 @@ You can safelist selectors and their children based on a regular expression with
 
 ```js
 const purgecss = await new PurgeCSS().purge({
-  content: [], // content
-  css: [], // css
+  content: [],
+  css: [],
   safelist: {
     deep: [/red$/]
   }
@@ -317,8 +317,8 @@ Finally, you can safelist whole selectors if any part of that selector matches a
 
 ```js
 const purgecss = await new PurgeCSS().purge({
-  content: [], // content
-  css: [], // css
+  content: [],
+  css: [],
   safelist: {
     greedy: [/red$/]
   }

packages/gulp-purgecss/src/index.ts

@@ -16,6 +16,13 @@ function getFiles(contentArray: string[]): string[] {
   }, []);
 }
 
+/**
+ * 
+ * @param options - options
+ * @returns 
+ * 
+ * @public
+ */
 function gulpPurgeCSS(options: UserDefinedOptions): internal.Transform {
   return through.obj(async function (file: VinylFile, _encoding, callback) {
     // empty

packages/gulp-purgecss/src/types/index.ts

@@ -1,5 +1,8 @@
 import { UserDefinedOptions as PurgeCSSUserDefinedOptions } from "purgecss";
 
+/**
+ * @public
+ */
 export interface UserDefinedOptions
   extends Omit<PurgeCSSUserDefinedOptions, "css" | "content"> {
   content: string[];

packages/postcss-purgecss/src/index.ts

@@ -4,8 +4,9 @@ import {
   defaultOptions,
   mergeExtractorSelectors,
   standardizeSafelist,
+  RawContent,
 } from "purgecss";
-import { RawContent, UserDefinedOptions } from "./types";
+import { UserDefinedOptions } from "./types";
 
 export * from "./types";
 
@@ -71,6 +72,13 @@ async function purgeCSS(
   }
 }
 
+/**
+ * 
+ * @param opts - opts
+ * @returns 
+ * 
+ * @public
+ */
 const purgeCSSPlugin: postcss.PluginCreator<UserDefinedOptions> = function (
   opts
 ) {

packages/postcss-purgecss/src/types/index.ts

@@ -1,32 +1,14 @@
-import { StringRegExpArray, UserDefinedSafelist } from "purgecss";
+import {
+  UserDefinedOptions as PurgeCSSUserDefinedOptions,
+  RawContent
+} from "purgecss";
 
-export interface RawContent<T = string> {
-  extension: string;
-  raw: T;
-}
-export interface RawCSS {
-  raw: string;
-}
-export type ExtractorFunction<T = string> = (content: T) => string[];
-export interface Extractors {
-  extensions: string[];
-  extractor: ExtractorFunction;
-}
 
-export interface UserDefinedOptions {
-  content?: Array<string | RawContent>;
+/**
+ * {@inheritDoc purgecss#UserDefinedOptions}
+ * 
+ * @public
+ */
+export interface UserDefinedOptions extends Omit<PurgeCSSUserDefinedOptions, "css"> {
   contentFunction?: (sourceFile: string) => Array<string | RawContent>;
-  defaultExtractor?: ExtractorFunction;
-  extractors?: Array<Extractors>;
-  fontFace?: boolean;
-  keyframes?: boolean;
-  output?: string;
-  rejected?: boolean;
-  stdin?: boolean;
-  stdout?: boolean;
-  variables?: boolean;
-  safelist?: UserDefinedSafelist;
-  blocklist?: StringRegExpArray;
-  skippedContentGlobs?: Array<string>;
-  dynamicAttributes?: string[];
 }

packages/purgecss-from-html/src/index.ts

@@ -1,6 +1,9 @@
 import parse5 from "parse5";
 import * as htmlparser2 from "parse5-htmlparser2-tree-adapter";
 
+/**
+ * @public
+ */
 export type ExtractorResultDetailed = {
   attributes: {
     names: string[];
@@ -90,6 +93,14 @@ const getSelectorsInNodes = (
   return result;
 };
 
+/**
+ * Get the potential selectors from HTML code
+ * 
+ * @param content - HTML code
+ * @returns the attributes, classes, ids, and tags from the HTML code
+ * 
+ * @public
+ */
 const purgecssFromHtml = (content: string): ExtractorResultDetailed => {
   const tree = parse5.parse(content, {
     treeAdapter: htmlparser2,

packages/purgecss-from-jsx/src/index.ts

@@ -16,6 +16,14 @@ type NodeState = {
 
 extend<NodeState>(walk.base);
 
+/**
+ * Create function to extract selectors from jsx code
+ * 
+ * @param options - acorn options
+ * @returns function to extract selectors from jsx code
+ * 
+ * @public
+ */
 function purgeFromJsx(options?: acorn.Options) {
   return (content: string): string[] => {
     // Will be filled during walk

packages/purgecss-from-pug/src/index.ts

@@ -1,5 +1,13 @@
 import lex from "pug-lexer";
 
+/**
+ * Get the potential selectors from Pug code
+ * 
+ * @param content - Pug code
+ * @returns the attributes, classes, ids, and tags from the Pug code
+ * 
+ * @public
+ */
 const purgeFromPug = (content: string): string[] => {
   const tokens = lex(content);
   const selectors: string[] = [];

packages/purgecss-from-tsx/src/index.ts

@@ -2,6 +2,14 @@ import purgeFromJsx from "@fullhuman/purgecss-from-jsx";
 import acorn from "acorn";
 import * as ts from "typescript";
 
+/**
+ * Create function to extract selectors from tsx code
+ * 
+ * @param options - acorn options
+ * @returns the function to extract selectors from tsx code
+ * 
+ * @public
+ */
 function purgeFromTsx(options?: {
   acornOptions?: acorn.Options;
   tsOptions?: ts.CompilerOptions;

packages/purgecss-webpack-plugin/src/index.ts

@@ -31,6 +31,9 @@ function isFileOfTypes(filename: string, extensions: string[]): boolean {
   return extensions.includes(extension);
 }
 
+/**
+ * @public
+ */
 export class PurgeCSSPlugin {
   options: UserDefinedOptions;
   purgedStats: PurgedStats = {};
@@ -101,6 +104,7 @@ export class PurgeCSSPlugin {
         };
 
         if (typeof options.safelist === "function") {
+          options.safelist
           options.safelist = options.safelist();
         }
 

packages/purgecss-webpack-plugin/src/types/index.ts

@@ -1,42 +1,38 @@
-import { ComplexSafelist, StringRegExpArray } from "purgecss";
+import type {
+  ComplexSafelist,
+  StringRegExpArray,
+  UserDefinedOptions as PurgeCSSUserDefinedOptions
+} from "purgecss";
 
-export interface RawContent<T = string> {
-  extension: string;
-  raw: T;
-}
-export interface RawCSS {
-  raw: string;
-}
-export type ExtractorFunction<T = string> = (content: T) => string[];
-export interface Extractors {
-  extensions: string[];
-  extractor: ExtractorFunction;
-}
 
+/**
+ * @public 
+ */
 export type PathFunction = () => string[];
+/**
+ * @public
+ */
 export type SafelistFunction = () => ComplexSafelist;
+/**
+ * @public
+ */
 export type BlocklistFunction = () => StringRegExpArray;
 
-export interface UserDefinedOptions {
+/**
+ * @public
+ */
+export type PurgedStats = {
+  [index: string]: string[];
+};
+
+/**
+ * @public
+ */
+export type UserDefinedOptions = Omit<PurgeCSSUserDefinedOptions, "css" | "content" | "safelist" | "blocklist"> & {
   paths: string[] | PathFunction;
-  defaultExtractor?: ExtractorFunction;
-  extractors?: Array<Extractors>;
-  fontFace?: boolean;
-  keyframes?: boolean;
   moduleExtensions?: string[];
-  output?: string;
-  rejected?: boolean;
-  stdin?: boolean;
-  stdout?: boolean;
-  variables?: boolean;
   verbose?: boolean;
-  safelist?: StringRegExpArray | ComplexSafelist | SafelistFunction;
-  blocklist?: StringRegExpArray | BlocklistFunction;
-  skippedContentGlobs?: Array<string>;
-  dynamicAttributes?: string[];
+  safelist: PurgeCSSUserDefinedOptions['safelist'] | SafelistFunction;
+  blocklist: PurgeCSSUserDefinedOptions['blocklist'] | BlocklistFunction;
   only?: string[];
 }
-
-export type PurgedStats = {
-  [index: string]: string[];
-};

packages/purgecss/src/ExtractorResultSets.ts

@@ -6,6 +6,9 @@ function mergeSets(into: Set<string>, from?: string[] | Set<string>): void {
   }
 }
 
+/**
+ * @public
+ */
 class ExtractorResultSets {
   private undetermined = new Set<string>();
   private attrNames = new Set<string>();

packages/rollup-plugin-purgecss/src/index.ts

@@ -6,6 +6,13 @@ import { UserDefinedOptions } from "./types";
 
 export * from "./types";
 
+/**
+ * 
+ * @param options - options
+ * @returns 
+ * 
+ * @public
+ */
 function pluginPurgeCSS(options: UserDefinedOptions): Plugin {
   const filter = createFilter(
     options.include || ["**/*.css"],

packages/rollup-plugin-purgecss/src/types/index.ts

@@ -1,39 +1,26 @@
-import { StringRegExpArray, UserDefinedSafelist } from "purgecss";
-
-export interface RawContent<T = string> {
-  extension: string;
-  raw: T;
-}
-export interface RawCSS {
-  raw: string;
-}
-export type ExtractorFunction<T = string> = (content: T) => string[];
-export interface Extractors {
-  extensions: string[];
-  extractor: ExtractorFunction;
-}
+import type {
+  RawContent,
+  UserDefinedOptions as PurgeCSSUserDefinedOptions,
+} from "purgecss";
 
+/**
+ * @public
+ */
 export type OutputFunction = (css: string, styles: string[]) => void;
 
-export interface UserDefinedOptions {
-  content: Array<string | RawContent>;
+/**
+ * {@inheritDoc purgecss#UserDefinedOptions}
+ *
+ * @public
+ */
+export type UserDefinedOptions = Omit<
+  PurgeCSSUserDefinedOptions,
+  "css" | "output" | "rejectedCss"
+> & {
   contentFunction?: (sourceFile: string) => Array<string | RawContent>;
-  defaultExtractor?: ExtractorFunction;
-  extractors?: Array<Extractors>;
-  fontFace?: boolean;
-  keyframes?: boolean;
-  output?: string | OutputFunction | boolean;
-  rejected?: boolean;
-  stdin?: boolean;
-  stdout?: boolean;
-  variables?: boolean;
-  safelist?: UserDefinedSafelist;
-  blocklist?: StringRegExpArray;
-  skippedContentGlobs?: Array<string>;
-  dynamicAttributes?: string[];
-
+  output: PurgeCSSUserDefinedOptions["output"] | OutputFunction | boolean;
   insert?: boolean;
   include?: string | RegExp | (string | RegExp)[];
   exclude?: string | RegExp | (string | RegExp)[];
   dest?: string;
-}
+};