diff --git a/docs/extractors.md b/docs/extractors.md
index d1cee5ba..2a12cb64 100644
--- a/docs/extractors.md
+++ b/docs/extractors.md
@@ -43,19 +43,19 @@ Using a specific extractor for an extension should provide you with the best acc
 You can use an extractor by settings the extractors option in the PurgeCSS config file.
 
 ```js
-import purgeJs from "purgecss-from-js";
-import purgeHtml from "purgecss-from-html";
+import { purgeCSSFromPug } from "purgecss-from-pug";
+import { purgeCSSFromHtml } from "purgecss-from-html";
 
 const options = {
   content: [], // files to extract the selectors from
   css: [], // css
   extractors: [
     {
-      extractor: purgeJs,
-      extensions: ["js"],
+      extractor: purgeCSSFromPug,
+      extensions: ["pug"],
     },
     {
-      extractor: purgeHtml,
+      extractor: purgeCSSFromHtml,
       extensions: ["html"],
     },
   ],
@@ -67,6 +67,21 @@ export default options;
 
 An extractor is a simple function that takes the content of a file as a string and returns an array of selectors. By convention, the name of the npm package is `purgecss-from-[typefile]` \(e.g. purgecss-from-pug\). Using this convention will allow users to look at the list of extractor on npm by searching `purgecss-from`.
 
+The function can returns either an array of selectors (tags, classes, ids) or the object below for better accuracy:
+
+```ts
+interface ExtractorResultDetailed {
+  attributes: {
+    names: string[];
+    values: string[];
+  };
+  classes: string[];
+  ids: string[];
+  tags: string[];
+  undetermined: string[];
+}
+```
+
 ```js
 const purgeFromJs = (content) => {
   // return array of css selectors
diff --git a/packages/purgecss-from-pug/README.md b/packages/purgecss-from-pug/README.md
index 36af0739..1d56605b 100644
--- a/packages/purgecss-from-pug/README.md
+++ b/packages/purgecss-from-pug/README.md
@@ -1,11 +1,22 @@
 # `purgecss-from-pug`
 
-> TODO: description
+A PurgeCSS extractor for PUG files that automatically generates a list of used CSS selectors from your PUG files. This extractor can be used with PurgeCSS to eliminate unused CSS and reduce the size of your production builds.
 
 ## Usage
 
 ```
-const purgecssFromPug = require('purgecss-from-pug');
+import { PurgeCSS } from 'purgecss'
+import { purgeCSSFromPug } from 'purgecss-from-pug'
+const options = {
+  content: [], // files to extract the selectors from
+  css: [], // css
+  extractors: [
+    {
+      extractor: purgeCSSFromPug,
+      extensions: ['pug']
+    },
+  ]
+}
 
-// TODO: DEMONSTRATE API
+const purgecss = await new PurgeCSS().purge();
 ```
diff --git a/packages/purgecss-from-pug/src/index.ts b/packages/purgecss-from-pug/src/index.ts
index 62da972d..0db7d1ca 100644
--- a/packages/purgecss-from-pug/src/index.ts
+++ b/packages/purgecss-from-pug/src/index.ts
@@ -1,3 +1,13 @@
+/**
+ * Pug extractor for PurgeCSS
+ *
+ * A PurgeCSS extractor for PUG files that automatically generates a list of
+ * used CSS selectors. This extractor can be used with PurgeCSS to eliminate 
+ * unused CSS and reduce the size of your production builds.
+ *
+ * @packageDocumentation
+ */
+
 import lex from "pug-lexer";
 import type { ExtractorResultDetailed } from "purgecss";