concat documentation not showing up on rxjs.dev #7009
Description
Describe the bug
Some awesome documentation exists in the file src/internal/observable/concat.ts as JSDoc.
However, it's not present on rxjs.dev.
What it currently looks like:
Expected behavior
I expect the documentation to show up on rxjs.dev.
It would look like this:
Reproduction code
# 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/concatReproduction 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.
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:
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:
// ...
$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:
[
{
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 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:
[
{
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.