Merge pull request #6 from mizdra/improve-api-documentation

Improve API documentation

.eslintrc.cjs

@@ -15,6 +15,17 @@ module.exports = {
     {
       files: ['*.ts', '*.tsx', '*.cts', '*.mts'],
       extends: ['@mizdra/mizdra/+typescript', '@mizdra/mizdra/+prettier'],
+      plugins: ['eslint-plugin-tsdoc'],
+      rules: {
+        'tsdoc/syntax': 'error',
+        // In tsdoc, if you define a method type in a property style, it will not be determined as a method.
+        // Therefore, it forces methods to be defined in method shorthand syntax.
+        '@typescript-eslint/method-signature-style': ['error', 'method'],
+        // In tsdoc, properties of a type defined with `interface` are included in the document,
+        // whereas those defined with `type` are omitted from the document.
+        // So we force types to be defined with `interface` whenever possible.
+        '@typescript-eslint/consistent-type-definitions': ['error', 'interface'],
+      },
     },
   ],
 };

.gitignore

@@ -134,3 +134,5 @@ dist
 
 # User
 /dist
+/tsdoc-metadata.json
+/temp

.prettierignore

@@ -1 +1,4 @@
 /dist
+/tsdoc-metadata.json
+/temp
+/docs/api

CONTRIBUTING.md

@@ -5,17 +5,9 @@ This is a guide for contributors.
 ## How to dev
 
 - `npm run build`: Build for production
-- `npm run dev`: Run for development
 - `npm run lint`: Run static-checking
 - `npm run test`: Run tests
-
-## How to update API documentation
-
-```bash
-documentation build src/index.ts --parse-extension ts -f md -c documentation.yml \
-  | add-text-to-markdown README.md --section "API documentation" --write \
-  && npm run lint:prettier -- --write
-```
+- `npm run update-api-documentation`: Update API documentation
 
 ## How to release
 

README.md

@@ -77,196 +77,4 @@ test('eslint reports lint errors', async () => {
 
 ## API documentation
 
-<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
-
-#### Table of Contents
-
-- [createIFF][1]
-  - [Parameters][2]
-- [CreateIFFResult#paths][3]
-- [CreateIFFResult#join][4]
-- [CreateIFFResult#addFixtures][5]
-  - [Parameters][6]
-- [CreateIFFResult#fork][7]
-  - [Parameters][8]
-- [CreateIFFResult#rmRootDir][9]
-- [CreateIFFResult#rmFixtures][10]
-- [CreateIFFResult#rootDir][11]
-- [CreateIFFOptions#rootDir][12]
-- [AddFixturesResult#paths][13]
-- [AddFixturesResult#paths][14]
-
-### createIFF
-
-Create fixtures in the specified directory.
-The path separator must be in POSIX format (`/`).
-Use of Windows path separator is an undefined behavior.
-
-```ts
-const iff = await createIFF(
-  {
-    'a.txt': 'a',
-    'b': {
-      'a.txt': 'b-a',
-    },
-    'c/a/a.txt': 'c-a-a',
-  },
-  fixturesDir,
-);
-```
-
-#### Parameters
-
-- `directory` **T** The definition of fixtures to be created.
-- `options` **CreateIFFOptions** Options for creating fixtures.
-
-Returns **[Promise][15]\\&lt;CreateIFFResult\\<T>>** An object that provides functions to manipulate the fixtures.
-
-### CreateIFFResult#paths
-
-The paths of the fixtures.
-For example, if you create a fixture `a.txt`, then `iff.paths['a.txt'] === iff.join('a.txt')`.
-
-```ts
-const iff = await createIFF(
-  {
-    'a.txt': 'a',
-    'b': {
-      'a.txt': 'b-a',
-    },
-    'c/a/a.txt': 'c-a-a',
-  },
-  fixturesDir,
-);
-expect(iff.paths).toStrictEqual({
-  'a.txt': iff.join('a.txt'),
-  'b': iff.join('b'),
-  'b/a.txt': iff.join('b/a.txt'),
-  'c': iff.join('c'),
-  'c/a': iff.join('c/a'),
-  'c/a/a.txt': iff.join('c/a/a.txt'),
-});
-```
-
-The `paths` keys are strictly typed. However, index signatures are excluded for convenience.
-
-```ts
-const iff = await createIFF(
-  {
-    'a.txt': 'a',
-    'b': {
-      'a.txt': 'b-a',
-    },
-    ['c.txt' as string]: 'c',
-    ['d' as string]: {
-      'a.txt': 'd-a',
-    },
-  },
-  fixturesDir,
-);
-expectType<{
-  'a.txt': string;
-  'b': string;
-  'b/a.txt': string;
-}>(iff.paths);
-```
-
-### CreateIFFResult#join
-
-Join `rootDir` and `paths`.
-That is, it is equivalent to `require('path').join(rootDir, ...paths)`.
-
-### CreateIFFResult#addFixtures
-
-Add fixtures to `rootDir`.
-
-#### Parameters
-
-- `directory` The definition of fixtures to be added.
-
-Returns **any** The paths to fixtures created with `createIFF` and added with `CreateIFFResult#addFixtures`.
-
-### CreateIFFResult#fork
-
-Change the root directory and take over the fixture you created.
-
-Internally, first a new root directory is created, and then the fixtures from the old root directory are copied into it.
-Finally, the fixtures specified in `additionalDirectory` are added to the new root directory.
-
-The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write,
-then a fallback copy mechanism is used.
-
-Example:
-
-```ts
-const baseIff = await createIFF({
-  'a.txt': 'a',
-  'b/a.txt': 'b-a',
-  },
-}, { rootDir: baseRootDir });
-const forkedIff = await baseIff.fork({
-  'b/b.txt': 'b-b',
-  'c.txt': 'c',
-}, { rootDir: forkedRootDir });
-
-// `forkedIff` inherits fixtures from `baseIff`.
-expect(await readFile(join(forkedRootDir, 'a.txt'), 'utf-8')).toBe('a');
-expect(await readFile(join(forkedRootDir, 'b/a.txt'), 'utf-8')).toBe('b-a');
-expect(await readFile(join(forkedRootDir, 'b/b.txt'), 'utf-8')).toBe('b-b');
-expect(await readFile(join(forkedRootDir, 'c.txt'), 'utf-8')).toBe('c');
-
-// The `baseIff` fixtures are left in place.
-expect(await readFile(join(baseRootDir, 'a.txt'), 'utf-8')).toBe('a');
-expect(await readFile(join(baseRootDir, 'b/a.txt'), 'utf-8')).toBe('b-a');
-```
-
-#### Parameters
-
-- `additionalDirectory` The definition of fixtures to be added.
-- `options` Options for creating fixtures.
-
-### CreateIFFResult#rmRootDir
-
-Delete `rootDir`.
-
-### CreateIFFResult#rmFixtures
-
-Delete fixtures under `rootDir`.
-
-### CreateIFFResult#rootDir
-
-The directory where fixtures are written.
-This directory is obtained by processing the directory specified in `CreateIFFOptions#rootDir`
-using `path.resolve`.
-
-### CreateIFFOptions#rootDir
-
-Root directory for fixtures.
-
-### AddFixturesResult#paths
-
-- **See**: CreateIFFResult#paths
-
-The paths of the added fixtures.
-
-### AddFixturesResult#paths
-
-- **See**: CreateIFFResult#paths
-
-The paths of the added fixtures.
-
-[1]: #createiff
-[2]: #parameters
-[3]: #createiffresultpaths
-[4]: #createiffresultjoin
-[5]: #createiffresultaddfixtures
-[6]: #parameters-1
-[7]: #createiffresultfork
-[8]: #parameters-2
-[9]: #createiffresultrmrootdir
-[10]: #createiffresultrmfixtures
-[11]: #createiffresultrootdir
-[12]: #createiffoptionsrootdir
-[13]: #addfixturesresultpaths
-[14]: #addfixturesresultpaths-1
-[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+See [/docs/api/index.md](/docs/api/index.md).

api-extractor.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
+  "apiReport": {
+    "enabled": false
+  },
+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json"
+  },
+  "dtsRollup": {
+    "enabled": false
+  }
+}

docs/api/index.md

@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+|  Package | Description |
+|  --- | --- |
+|  [@mizdra/inline-fixture-files](./inline-fixture-files.md) | The utility for writing fixture files inline. |
+

docs/api/inline-fixture-files.addfixturesresult.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@mizdra/inline-fixture-files](./inline-fixture-files.md) &gt; [AddFixturesResult](./inline-fixture-files.addfixturesresult.md)
+
+## AddFixturesResult interface
+
+The return of [CreateIFFResult.addFixtures()](./inline-fixture-files.createiffresult.addfixtures.md)<!-- -->.
+
+**Signature:**
+
+```typescript
+export interface AddFixturesResult<T extends Directory, U extends Directory> 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [paths](./inline-fixture-files.addfixturesresult.paths.md) |  | FlattenDirectory&lt;T&gt; &amp; FlattenDirectory&lt;U&gt; | The paths to fixtures created with [createIFF()](./inline-fixture-files.createiff.md) and added with [CreateIFFResult.addFixtures()](./inline-fixture-files.createiffresult.addfixtures.md)<!-- -->. See [CreateIFFResult.paths](./inline-fixture-files.createiffresult.paths.md) for details. |
+

docs/api/inline-fixture-files.addfixturesresult.paths.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@mizdra/inline-fixture-files](./inline-fixture-files.md) &gt; [AddFixturesResult](./inline-fixture-files.addfixturesresult.md) &gt; [paths](./inline-fixture-files.addfixturesresult.paths.md)
+
+## AddFixturesResult.paths property
+
+The paths to fixtures created with [createIFF()](./inline-fixture-files.createiff.md) and added with [CreateIFFResult.addFixtures()](./inline-fixture-files.createiffresult.addfixtures.md)<!-- -->. See [CreateIFFResult.paths](./inline-fixture-files.createiffresult.paths.md) for details.
+
+**Signature:**
+
+```typescript
+paths: FlattenDirectory<T> & FlattenDirectory<U>;
+```

docs/api/inline-fixture-files.createiff.md

@@ -0,0 +1,48 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@mizdra/inline-fixture-files](./inline-fixture-files.md) &gt; [createIFF](./inline-fixture-files.createiff.md)
+
+## createIFF() function
+
+Create fixtures in the specified directory.
+
+**Signature:**
+
+```typescript
+export declare function createIFF<const T extends Directory>(directory: T, options: CreateIFFOptions): Promise<CreateIFFResult<T>>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  directory | T | The definition of fixtures to be created. |
+|  options | [CreateIFFOptions](./inline-fixture-files.createiffoptions.md) | Options for creating fixtures. |
+
+**Returns:**
+
+Promise&lt;[CreateIFFResult](./inline-fixture-files.createiffresult.md)<!-- -->&lt;T&gt;&gt;
+
+An object that provides functions to manipulate the fixtures.
+
+## Remarks
+
+The path must be in POSIX-style (`'dir/file.txt'`<!-- -->). Use of Windows-style path (`'dir\\file.txt'`<!-- -->) is an undefined behavior.
+
+## Example
+
+
+```ts
+const iff = await createIFF(
+  {
+  'a.txt': 'a',
+  'b': {
+    'a.txt': 'b-a',
+  },
+  'c/a/a.txt': 'c-a-a',
+}, fixturesDir);
+expect(await readFile(join(fixturesDir, 'a.txt'), 'utf-8')).toBe('a');
+expect(await readFile(join(fixturesDir, 'b/a.txt'), 'utf-8')).toBe('b-a');
+expect(await readFile(join(fixturesDir, 'c/a/a.txt'), 'utf-8')).toBe('c-a-a');
+```
+

docs/api/inline-fixture-files.createiffoptions.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@mizdra/inline-fixture-files](./inline-fixture-files.md) &gt; [CreateIFFOptions](./inline-fixture-files.createiffoptions.md)
+
+## CreateIFFOptions interface
+
+The options for [createIFF()](./inline-fixture-files.createiff.md)<!-- -->.
+
+**Signature:**
+
+```typescript
+export interface CreateIFFOptions 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [rootDir](./inline-fixture-files.createiffoptions.rootdir.md) |  | string | Root directory for fixtures. |
+

docs/api/inline-fixture-files.createiffoptions.rootdir.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@mizdra/inline-fixture-files](./inline-fixture-files.md) &gt; [CreateIFFOptions](./inline-fixture-files.createiffoptions.md) &gt; [rootDir](./inline-fixture-files.createiffoptions.rootdir.md)
+
+## CreateIFFOptions.rootDir property
+
+Root directory for fixtures.
+
+**Signature:**
+
+```typescript
+rootDir: string;
+```