add support for namespaces (#24)

.changeset/cold-cycles-hope.md

@@ -0,0 +1,5 @@
+---
+"@effect/docgen": patch
+---
+
+add support for namespaces

.changeset/lovely-rice-guess.md

@@ -0,0 +1,5 @@
+---
+"@effect/docgen": patch
+---
+
+BugFix: remove stale modules from /docs folder

docs/modules/Domain.ts.md

@@ -21,6 +21,7 @@ Added in v1.0.0
   - [createInterface](#createinterface)
   - [createMethod](#createmethod)
   - [createModule](#createmodule)
+  - [createNamespace](#createnamespace)
   - [createProperty](#createproperty)
   - [createTypeAlias](#createtypealias)
 - [instances](#instances)
@@ -35,6 +36,7 @@ Added in v1.0.0
   - [Interface (interface)](#interface-interface)
   - [Method (interface)](#method-interface)
   - [Module (interface)](#module-interface)
+  - [Namespace (interface)](#namespace-interface)
   - [Property (interface)](#property-interface)
   - [TypeAlias (interface)](#typealias-interface)
 
@@ -138,12 +140,28 @@ export declare const createModule: (
   functions: ReadonlyArray<Function>,
   typeAliases: ReadonlyArray<TypeAlias>,
   constants: ReadonlyArray<Constant>,
-  exports: ReadonlyArray<Export>
+  exports: ReadonlyArray<Export>,
+  namespaces: ReadonlyArray<Namespace>
 ) => Module
 ```
 
 Added in v1.0.0
 
+## createNamespace
+
+**Signature**
+
+```ts
+export declare const createNamespace: (
+  documentable: Documentable,
+  interfaces: ReadonlyArray<Interface>,
+  typeAliases: ReadonlyArray<TypeAlias>,
+  namespaces: ReadonlyArray<Namespace>
+) => Namespace
+```
+
+Added in v1.0.0
+
 ## createProperty
 
 **Signature**
@@ -236,6 +254,16 @@ Added in v1.0.0
 
 ## Export (interface)
 
+These are manual exports, like:
+
+```ts
+const _null = ...
+
+export {
+  _null as null
+}
+```
+
 **Signature**
 
 ```ts
@@ -298,6 +326,22 @@ export interface Module extends Documentable {
   readonly typeAliases: ReadonlyArray<TypeAlias>
   readonly constants: ReadonlyArray<Constant>
   readonly exports: ReadonlyArray<Export>
+  readonly namespaces: ReadonlyArray<Namespace>
+}
+```
+
+Added in v1.0.0
+
+## Namespace (interface)
+
+**Signature**
+
+```ts
+export interface Namespace extends Documentable {
+  readonly _tag: 'Namespace'
+  readonly interfaces: ReadonlyArray<Interface>
+  readonly typeAliases: ReadonlyArray<TypeAlias>
+  readonly namespaces: ReadonlyArray<Namespace>
 }
 ```
 

docs/modules/Parser.ts.md

@@ -20,6 +20,7 @@ Added in v1.0.0
   - [parseFunctions](#parsefunctions)
   - [parseInterfaces](#parseinterfaces)
   - [parseModule](#parsemodule)
+  - [parseNamespaces](#parsenamespaces)
   - [parseTypeAliases](#parsetypealiases)
 
 ---
@@ -98,6 +99,16 @@ export declare const parseModule: Effect.Effect<Config.Config | Source, string[]
 
 Added in v1.0.0
 
+## parseNamespaces
+
+**Signature**
+
+```ts
+export declare const parseNamespaces: Effect.Effect<Config.Config | Source, string[], Domain.Namespace[]>
+```
+
+Added in v1.0.0
+
 ## parseTypeAliases
 
 **Signature**

src/Core.ts

@@ -416,13 +416,17 @@ const getModuleMarkdownFiles = (modules: ReadonlyArray<Domain.Module>) =>
 // -------------------------------------------------------------------------------------
 
 const writeMarkdown = (files: ReadonlyArray<FileSystem.File>) =>
-  Effect.map(Config.Config, (config) => join(config.outDir, "**/*.ts.md")).pipe(
-    Effect.tap((pattern) => Effect.logDebug(`deleting ${chalk.black(pattern)}`)),
-    Effect.flatMap((pattern) =>
-      Effect.flatMap(FileSystem.FileSystem, (fileSystem) => fileSystem.removeFile(pattern))
-    ),
-    Effect.flatMap(() => writeFiles(files))
-  )
+  Effect.gen(function*(_) {
+    const config = yield* _(Config.Config)
+    const fileSystem = yield* _(FileSystem.FileSystem)
+    const pattern = join(config.outDir, "**/*.ts.md")
+    yield* _(Effect.logDebug(`deleting ${chalk.black(pattern)}`))
+    const paths = yield* _(fileSystem.glob(pattern))
+    yield* _(
+      Effect.forEach(paths, (path) => fileSystem.removeFile(path), { concurrency: "unbounded" })
+    )
+    return yield* _(writeFiles(files))
+  })
 
 const MainLayer = Logger.replace(Logger.defaultLogger, SimpleLogger).pipe(
   Layer.merge(ChildProcess.ChildProcessLive),

src/Domain.ts

@@ -16,8 +16,15 @@ export interface Module extends Documentable {
   readonly typeAliases: ReadonlyArray<TypeAlias>
   readonly constants: ReadonlyArray<Constant>
   readonly exports: ReadonlyArray<Export>
+  readonly namespaces: ReadonlyArray<Namespace>
 }
 
+/**
+ * @category model
+ * @since 1.0.0
+ */
+export type Example = string
+
 /**
  * @category model
  * @since 1.0.0
@@ -96,6 +103,16 @@ export interface Constant extends Documentable {
 }
 
 /**
+ * These are manual exports, like:
+ *
+ * ```ts
+ * const _null = ...
+ *
+ * export {
+ *   _null as null
+ * }
+ * ```
+ *
  * @category model
  * @since 1.0.0
  */
@@ -108,7 +125,12 @@ export interface Export extends Documentable {
  * @category model
  * @since 1.0.0
  */
-export type Example = string
+export interface Namespace extends Documentable {
+  readonly _tag: "Namespace"
+  readonly interfaces: ReadonlyArray<Interface>
+  readonly typeAliases: ReadonlyArray<TypeAlias>
+  readonly namespaces: ReadonlyArray<Namespace>
+}
 
 // -------------------------------------------------------------------------------------
 // constructors
@@ -146,7 +168,8 @@ export const createModule = (
   functions: ReadonlyArray<Function>,
   typeAliases: ReadonlyArray<TypeAlias>,
   constants: ReadonlyArray<Constant>,
-  exports: ReadonlyArray<Export>
+  exports: ReadonlyArray<Export>,
+  namespaces: ReadonlyArray<Namespace>
 ): Module => ({
   ...documentable,
   path,
@@ -155,7 +178,8 @@ export const createModule = (
   functions,
   typeAliases,
   constants,
-  exports
+  exports,
+  namespaces
 })
 
 /**
@@ -266,6 +290,23 @@ export const createExport = (
   signature
 })
 
+/**
+ * @category constructors
+ * @since 1.0.0
+ */
+export const createNamespace = (
+  documentable: Documentable,
+  interfaces: ReadonlyArray<Interface>,
+  typeAliases: ReadonlyArray<TypeAlias>,
+  namespaces: ReadonlyArray<Namespace>
+): Namespace => ({
+  _tag: "Namespace",
+  ...documentable,
+  interfaces,
+  typeAliases,
+  namespaces
+})
+
 /**
  * @category instances
  * @since 1.0.0

src/Markdown.ts

@@ -15,6 +15,7 @@ type Printable =
   | Domain.Function
   | Domain.Interface
   | Domain.TypeAlias
+  | Domain.Namespace
 
 const bold = (s: string) => `**${s}**`
 
@@ -34,6 +35,8 @@ const h2 = createHeader(2)
 
 const h3 = createHeader(3)
 
+const h4 = createHeader(4)
+
 const getSince: (v: Option.Option<string>) => string = Option.match({
   onNone: () => "",
   onSome: (v) => paragraph(`Added in v${v}`)
@@ -91,9 +94,7 @@ const getProperty = (p: Domain.Property): string =>
   )
 
 const getStaticMethods = (methods: ReadonlyArray<Domain.Method>): string =>
-  ReadonlyArray.map(methods, (method) => getStaticMethod(method) + "\n\n").join(
-    ""
-  )
+  ReadonlyArray.map(methods, (method) => getStaticMethod(method) + "\n\n").join("")
 
 const getMethods = (methods: ReadonlyArray<Domain.Method>): string =>
   ReadonlyArray.map(methods, (method) => getMethod(method) + "\n\n").join("")
@@ -166,24 +167,51 @@ const fromFunction = (f: Domain.Function): string =>
     getSince(f.since)
   )
 
-const fromInterface = (i: Domain.Interface): string =>
+const fromInterface = (i: Domain.Interface, indentation: number): string =>
   paragraph(
-    h2(getTitle(i.name, i.deprecated, "(interface)")),
+    getHeaderByIndentation(indentation)(getTitle(i.name, i.deprecated, "(interface)")),
     getDescription(i.description),
     getSignature(i.signature),
     getExamples(i.examples),
     getSince(i.since)
   )
 
-const fromTypeAlias = (ta: Domain.TypeAlias): string =>
+const fromTypeAlias = (ta: Domain.TypeAlias, indentation: number): string =>
   paragraph(
-    h2(getTitle(ta.name, ta.deprecated, "(type alias)")),
+    getHeaderByIndentation(indentation)(getTitle(ta.name, ta.deprecated, "(type alias)")),
     getDescription(ta.description),
     getSignature(ta.signature),
     getExamples(ta.examples),
     getSince(ta.since)
   )
 
+const getHeaderByIndentation = (indentation: number) => {
+  switch (indentation) {
+    case 0:
+      return h2
+    case 1:
+      return h3
+    case 2:
+      return h4
+  }
+  throw new Error(`Unsupported namespace nesting: ${indentation + 1}`)
+}
+
+const fromNamespace = (ns: Domain.Namespace, indentation: number): string =>
+  paragraph(
+    paragraph(
+      getHeaderByIndentation(indentation)(getTitle(ns.name, ns.deprecated, "(namespace)")),
+      getDescription(ns.description),
+      getExamples(ns.examples),
+      getSince(ns.since)
+    ),
+    ReadonlyArray.map(ns.interfaces, (i) => fromInterface(i, indentation + 1) + "\n\n").join(""),
+    ReadonlyArray.map(ns.typeAliases, (typeAlias) =>
+      fromTypeAlias(typeAlias, indentation + 1) + "\n\n").join(""),
+    ReadonlyArray.map(ns.namespaces, (namespace) =>
+      fromNamespace(namespace, indentation + 1) + "\n\n").join("")
+  )
+
 /** @internal */
 export const fromPrintable = (p: Printable): string => {
   switch (p._tag) {
@@ -196,9 +224,11 @@ export const fromPrintable = (p: Printable): string => {
     case "Function":
       return fromFunction(p)
     case "Interface":
-      return fromInterface(p)
+      return fromInterface(p, 0)
     case "TypeAlias":
-      return fromTypeAlias(p)
+      return fromTypeAlias(p, 0)
+    case "Namespace":
+      return fromNamespace(p, 0)
   }
 }
 
@@ -209,7 +239,8 @@ const getPrintables = (module: Domain.Module): ReadonlyArray<Printable> =>
     module.exports,
     module.functions,
     module.interfaces,
-    module.typeAliases
+    module.typeAliases,
+    module.namespaces
   ])
 
 /**