* trying out api-extractor.
* works with our setup of build.
* wip.
* changed the packages so it works better with the api-extractor.
* Changes to make the api-extractor to work.
* cleaned up the api-extractor config files.
* added some more documentation.
* added tsdoc-metadata to gitignore.
* removed the generated docs (will do that in another PR).
* added execute permission to script for generating dosc.
* added so we will push generated docs to branch.
* will clean packages_api on abort.
* Fixed failing tests.
* fixed formatting issue with typedoc comment.
* temporarily disabled tslint rules about namespace until https://github.com/microsoft/rushstack/issues/1029 is resolved
* temporary enabled bable namespaces.
* updated build script.
* updated script.
* updated script with some colors.
* changed to camelCase.
* removed spacing.
* Starting to add documentation guidelines.
* added examples headline.
* added parameters and return values.
* Fixed merge error.
* changed so we use the eslint ignore syntax.
* changed to correct eslint ingnore comment.
* fixed some spelling errors reported by codespell.
* added script to generate docs in current folder.
* lerna bootstrap.
* removed file that should be ignored.
* updated locKFILE.
* referenced the code comments guidelines.
* updated packages.
* updated deps.
1. [Set stability of an API](#set-stability-of-an-api)
1. [Deprecate an API](#deprecate-an-api)
1. [Specify parameters](#specify-parameters)
1. [Set return values](#set-return-values)
____
## Add package description
Each package has an overview explaining the overall responsibility and usage of the package.
You can document this description with [`@packageDocumentation`](https://api-extractor.com/pages/tsdoc/tag_packagedocumentation/) tag.
Add this tag to the `<packageRoot>/src/index.ts` entry file to have one place for the package description.
## Set stability of an API
All `exported` apis from the package should have a release tag to indicate its stability.
- [`@alpha`](https://api-extractor.com/pages/tsdoc/tag_alpha/) - early draft of api and will probably change.
- [`@beta`](https://api-extractor.com/pages/tsdoc/tag_beta/) - close to being stable but might change.
- [`@public`](https://api-extractor.com/pages/tsdoc/tag_public/) - ready for useage in production.
- [`@internal`](https://api-extractor.com/pages/tsdoc/tag_internal/) - for internal use only.
### Main stability of APIs
Add a tag to mark the stability of the whole exported `class/interface/function/type` etc.
Please place the `release tag` at the bottom of the comment to make it consistent among files and easier to read.
**Do:**
```typescript
/**
* Will help to create DataFrame objects and handle
* the heavy lifting of creating a complex object.
*
* @example
* ```typescript
* const dataFrame = factory.create();
* ```
*
* @public
**/
export class DataFrameFactory {
create(): DataFrame { }
}
```
**Don't**
```typescript
/**
* Will help to create DataFrame objects and handle
* the heavy lifting of creating a complex object.
*
* @public
* @example
* ```typescript
* const dataFrame = factory.create();
* ```
**/
export class DataFrameFactory {
create(): DataFrame { }
}
```
### Partial stability of APIs
Add the main stability of the API at the top according to [Main stability of API](#main-stability-of-api).
Then override the non-stable parts of the API with the proper [release tag](#release-tags). This should also be place at the bottom of the comment block.
**Do:**
```typescript
/**
* Will help to create DataFrame objects and handle
* the heavy lifting of creating a complex object.
*
* @example
* ```typescript
* const dataFrame = factory.create();
* ```
*
* @public
**/
export class DataFrameFactory {
create(): DataFrame { }
/**
* @beta
**/
createMany(): DataFrames[] {}
}
```
**Don't**
```typescript
/**
* Will help to create DataFrame objects and handle
* the heavy lifting of creating a complex object.
*
* @example
* ```typescript
* const dataFrame = factory.create();
* ```
**/
export class DataFrameFactory {
/**
* @public
**/
create(): DataFrame { }
/**
* @beta
**/
createMany(): DataFrame[] {}
}
```
## Deprecate an API
If you want to mark an API as deprecated to signal that this API will be removed in the future, then add the [`@deprecated`](https://api-extractor.com/pages/tsdoc/tag_deprecated/) tag.
If applicable add a reason why the API is deprecated directly after the `@deprecated tag`.
## Specify parameters
If you want to specify the possible parameters that can be passed to an API, then add the [`@param`](https://api-extractor.com/pages/tsdoc/tag_param/) tag.
This attribute can be skipped if the type provided by `typescript` and the function comment or the function name is enough to explain what the parameters are.
**Do:**
```typescript
/**
* Will help to create a resource resovler depending
* on the current execution context.
*
* @param context - The current execution context.
* @returns FileResolver if executed on the server otherwise a HttpResolver.
If you want to specify the return value from a function you can use the [`@returns`](https://api-extractor.com/pages/tsdoc/tag_returns/) tag.
This attribute can be skipped if the type provided by `typescript` and the function comment or the function name is enough to explain what the function returns.
**Do:**
```typescript
/**
* Will help to create a resource resovler depending
* on the current execution context.
*
* @param context - The current execution context.
* @returns FileResolver if executed on the server otherwise a HttpResolver.
Marcus Andersson
5 years ago
committed by