JSDoc documentation versus documentation in *.d.ts

[papb]

Is it intended that the two parameter documentations below aren't the same?

sequelize/lib/sequelize.js

Line 319 in abfe7e5

* @param {Object} attributes An object, where each attribute is a column of the table. See {@link Model.init}

sequelize/types/lib/sequelize.d.ts

Lines 1017 to 1018 in abfe7e5

	* @param attributes An object, where each attribute is a column of the table. Each column can be either a
	* DataType, a string or a type-description object, with the properties described below:

Also, since now we have duplicated documentation on the source files and on .d.ts files, is there a concrete way to prevent documentation from being updated only in one place?

Pinging @SimonSchick since I know you're highly involved in the typescript things in Sequelize. Thanks for looking!

[SimonSchick]

tl;dr the typings used to be separate, so documentation was duplicated in many places.
I hope we can eventually use TS for sequelize itself and/or generate documentation entirely from the type definitions and make it a single point of truth as the typings are subjectively better documentation than the current jsdoc in the source.

[papb]

@SimonSchick - I see. Thanks for the fast response 😁 While sequelize itself doesn't use TS, do you know any tool to generate documentation from *.d.ts files?

Also, is it possible to use syntax similar to {@link} in the *.d.ts documentation? (I am very new to TS, sorry if it is a trivial question). If not, what is a good strategy when documenting to replace things like {@link} in the *.d.ts documentation?

[SimonSchick]

I don't think that @link works very well in TS but you're welcome to try.

As for generating documentation, I worked with some generators before but their capabilities were extremely limited, you are welcome to make suggestions.

[papb]

I see. I've asked a question in typedoc to see if it would be possible to use that. Other than that, I have no idea...

Maybe we will have to put up with duplicated docs while sequelize doesn't move to TS. It's not ideal but I don't think it's that terrible either...

[papb]

@SimonSchick - Apparently it is possible to use typedoc. I do not have the time to try it out though... Just letting you know.

[ALiangLiang]

I just tried to use this generator.

$ typedoc --exclude node_modules/ --includeDeclarations --out typedoc/ --readme README.md --name Sequelize types/lib

[SimonSchick]

Ultimately this is up to @sushantdhiman as this would drastically alter the current documentation and might make it harder for non TS users to read, we could co-host a type-doc version but that's not my call 😄

[github-actions]

This issue has been automatically marked as stale because it has been open for 14 days without activity. It will be closed if no further activity occurs within the next 14 days. If this is still an issue, just leave a comment or remove the "stale" label. 🙂