svelte
svelte copied to clipboard
sveltejs
more jsdoc documentation for runtime parts
Describe the problem
the low level documentation (https://svelte.dev/docs) is not really easy to use ( and incomplete in some cases) I think if the runtime function contain JSDOC it will help a lot and give the developers an easier way to discover api documentation
additionally it is possible to replace the https://svelte.dev/docs with the generated docs ( with some thing like https://typedoc.org/ )
I am not sure but it would also make svelte maintainers life easier because keeping the docs with code might be a pain 🤷♂️
Describe the proposed solution
add JSDOC for runtime functions It wont take too much of time because text already exists in svelte.dev/docs
Alternatives considered
I have no idea about alternatives :)
Importance
would make my life easier
I think it is a good addition, though it would bear more maintenance work to make sure docs are updated in both places. Still would be better for the end-users though.
I think it is a good addition, though it would bear more maintenance work to make sure docs are updated in both places. Still would be better for the end-users though.
typedoc could generate json output and it is possible to convert that into the existing markdown format so the use experience remains the same.
typedoc could generate json output and it is possible to convert that into the existing markdown format so the use experience remains the same.
We had talked about this in the past and concluded that the typedocs style isn't really user-friendly. I think for now we can stick with the hand-crafted docs, and update the jsdoc in-code only.
Also, I think having the jsdoc link back the the Svelte docs might be useful too, if you're already working on it 😅
concluded that the typedocs style isn't really user-friendly
I absolutely agree. There is a difference between documentation and an auto-generated API reference. To me these are two separate things (I unfortunately have to work with https://microsoft.github.io/monaco-editor/api/index.html regularly, so :-1: on having only TypeDocs)
It wont be like that
It is possible to generate exactly the same dicumentation based on jsdoc
I am actually just coping docs markdown into jsdoc
And then I will use typedoc to extract them from jsdoc and then create the documentation which will be the same as current docs !
oh now I finally found out that its not possible to completely generate the same result :grimacing:
I think this issue should be closed? I want to contribute to Svelte, and came here as a good first issue :).
Could you suggest something else to tackle, maybe?
@safwansamsudeen look at #8849 or for search issues with the tag good first issue
