documentationjs / documentationjs/documentation

Proper usage with Typescript

Open
#1,605 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
JavaScript
Stars
5.8k
Forks
481
PR merge metrics
No merged PRs in 30d

Description

_Version 14.0.2_

Hi,

I'm working with Typescript and I'm wondering which is the proper way to deal with type specifications. Let me propose an example to better explain myself.

### Example
_The code below can also be found as a working example here: https://codesandbox.io/p/sandbox/nice-cloud-3rxyg8_

Suppose the following code:
```ts
// index.ts
type Address = { street: string; city: string };
type Email = { email: string };
type Phone = { phone: string };

/**
* My User lorem ipsum
*/
export type User = {
name: string;
address: Address;
contacts: Email & Phone;
};

/**
* An example of person lorem ipsum
*/
export interface Person {
name: string;
surname: string;
address: Address;
}
```

and suppose the following command:
```sh
$ documentation readme src/index.ts --parse-extension ts --section=API
```

I receive the following output (in my README.md file):
```md

#### Table of Contents

* [User](#user)
* [Properties](#properties)
* [Person](#person)

### User

My User lorem ipsum

Type: {name: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), address: Address, contacts: any}

#### Properties

* `name` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
* `address` **Address**
* `contacts` **any**

### Person

An example of person
```

### Expectations
I spotted some issues in the outcome. I don't know if they are because of a misuse by myself, a known bug, a missing feature, or a feature `documentation.js` won't support at all. I read the docs and I found no clues about the will to support Typescript types and any known issues.

1. `Person` members aren't listed just because it's written as an `interface` instead of a `type`
2. `User.address` is of type `Address`, which is not meant to be exposed; Shouldn't it be _expanded_ in the property definition?
3. `User.contacts` isn't resolved because of the intersection `&`
4. How can I add a description text for each property?

Apologize if any of these issues were already documented.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.