concat documentation not showing up on rxjs.dev
envgap__reactivex__rxjs-7009
01 / FAILURE SIGNATURE
As reported upstream
No identifying execution failure has been captured.
Not a benchmark task.
- In a clean container the reported failure did not reproduce, or the known fix did not make the project run.
02 / ENVIRONMENT RECIPE
- Base commit
5df07eb45c11ffd3df28595000f627f7a3be6577- Manifest
docs_app/package.json- Reproduce
Awaiting issue-specific recipe- Run under trace
Awaiting a meaningful runtime command
03 / ORIGINAL ISSUE TEXT
reactivex/rxjs #7009 · read the original issue
### Describe the bug
Some awesome documentation exists in the file [`src/internal/observable/concat.ts`](https://github.com/ReactiveX/rxjs/blob/master/src/internal/observable/concat.ts) as JSDoc.
However, it's not present on [rxjs.dev](https://rxjs.dev/api/index/function/concat).
What it currently looks like:
<img width="637" alt="image" src="https://user-images.githubusercontent.com/22200293/177014592-00024d38-9ce6-4646-a6be-4821faedbd68.png">
### Expected behavior
I expect the documentation to show up on [rxjs.dev](https://rxjs.dev/api/index/function/concat).
It would look like this:
<img width="637" alt="image" src="https://user-images.githubusercontent.com/22200293/177014617-15ecc933-7338-4974-884d-0e1692b15e6b.png">
### Reproduction code
```typescript
# Non-local:
- Go to: https://rxjs.dev/api/index/function/concat
# Local:
- cd docs_app
- npm run docs
- npm run start
- Go to: http://localhost:4200/api/index/function/concat
```
### Reproduction URL
https://rxjs.dev/api/index/function/concat
### Version
7.5.5
### Environment
_No response_
### Additional context
I have narrowed the problem down to the TypeScript package in [dgeni-packages](https://github.com/angular/dgeni-packages#typescript-package).
It produces wrong information about the function overloads. I should probably open an issue there, but I want to know what you think about this first. Maybe I'm totally off. Also, I think you'll be quicker to respond and might be interested in the temporary fix I have.
## How to test this.
I wrote this function to debug this issue:
```js
function analyzeTypes(filename, docs) {
const relavantDocs = docs.reduce((acc, doc) => {
if (!doc.fileInfo?.relativePath?.includes(filename)) {
return acc;
}
return [
...acc,
{
id: doc.id,
docType: doc.docType,
type: doc.type,
// Note: These line numbers don't seem to match *exactly* with the file.
// Not sure why. They almost match though.
startingLine: doc.startingLine,
endingLine: doc.endingLine,
overloads: doc.overloads?.map((doc) => doc.id),
},
];
}, []);
console.log();
console.log(`-- TYPE ANALYSIS ${filename} --`);
console.log();
console.log(relavantDocs);
console.log();
}
```
It can be defined and called in `docs_app/tools/transforms/angular-api-package/processors/filterContainedDocs.js`. Here is where and how I call it:
```js
// ...
$process: function (docs) {
var docTypes = this.docTypes; // line 11
analyzeTypes('internal/observable/concat.ts', docs);
// ...
```
The key information it logs is the `docType` of the docs array elements. Context: `filterContainedDocs` filters away certain docTypes; One being `'function-overload'`
## Current output of my function:
```js
[
{
id: 'index/concat',
docType: 'function',
type: '',
startingLine: 5,
endingLine: 6,
overloads: [ 'index/concat()', 'index/concat(...args: any[])' ]
},
{
id: 'index/concat()',
docType: 'function-overload',
type: '',
startingLine: 7,
endingLine: 7,
overloads: undefined
},
{
id: 'index/concat(...args: any[])',
docType: 'function-overload',
type: 'Observable<unknown>',
startingLine: 10,
endingLine: 114,
overloads: undefined
},
{
id: 'index/concat~args',
docType: 'parameter',
type: 'any[]',
startingLine: 113,
endingLine: 112,
overloads: undefined
}
]
```
Notice the third element with id `index/concat(...args: any[])`. It got a docType of `'function-overload'` (clearly wrong. It's not an overload) resulting in it being filtered away.
## Quickfix
I'm still not exactly sure **why** this happens. I do know one fast way to fix it though: change the order of the overloads.
[`src/internal/observable/concat.ts`](https://github.com/ReactiveX/rxjs/blob/master/src/internal/observable/concat.ts) contains two overloads at the beginning of the file. If we move them to the bottom of the file we now get another output from my function -
## Quickfix output of my function:
```js
[
{
id: 'index/concat',
docType: 'function',
type: 'Observable<unknown>',
startingLine: 5,
endingLine: 109,
overloads: [ 'index/concat()', 'index/concat()' ]
},
{
id: 'index/concat~args',
docType: 'parameter',
type: 'any[]',
startingLine: 108,
endingLine: 107,
overloads: undefined
},
{
id: 'index/concat()',
docType: 'function-overload',
type: '',
startingLine: 110,
endingLine: 111,
overloads: undefined
},
{
id: 'index/concat()',
docType: 'function-overload',
type: '',
startingLine: 112,
endingLine: 112,
overloads: undefined
}
]
```
It's now correct! (this produces the beautiful docs in the screenshot from "**Expected behavior**" )
I would be more than happy to submit a PR with this fix. I think a few other operators has this problem. I could run through them all to make sure the ordering allows for expected docs.
04 / LABELS
Labels from the report text only; not yet run
No supported category has been assigned.
Label rules and the text that matched
[]