search

zmxv / react-native-sound

React Native module for playing sound clips
MIT License
2.79k stars 748 forks source link

Better documentation #615

Open Sharcoux opened 4 years ago

Sharcoux commented 4 years ago

:clipboard: Description

I think it would be great to have a full API documentation with all possible functions exposed by the Sound object, their parameters and their effect.

:microphone: Motivation

The current documentation is hard to read, and could lead to a massive loss of time both for developers coming here the first time, and maintainers that will have to answer questions.

:bulb: Alternatives

The sound.js file could be documented, leading to a better understanding of what the functions are actually doing. For instance, there is a setMode function. Cool... What does it do? What kind of parameters are accepted? What modes can we set? And what about setCategory?

paulmelnikow commented 4 years ago

Agreed! We could start adding doc comments and use eslint-plugin-jsdoc to validate them. Then the docs could be generated from that (and meanwhile, referred to in the source). I was also thinking it might make sense to put the documentation in the TypeScript types because that way the parameter and return types will also be documented.

Would you be up for working on that?

Sharcoux commented 4 years ago

I don't mind documenting the part I understand, but I asked for documentation because most part remains obscure to me. I don't know much about TypeScript.

paulmelnikow commented 4 years ago

I don't mind documenting the part I understand, but I asked for documentation because most part remains obscure to me.

I'm in the same situation; we're learning as we go.

There is actually a bunch of documentation in https://github.com/zmxv/react-native-sound/blob/master/index.d.ts ; maybe that's not such a bad start!

Sharcoux commented 4 years ago

Oh... So actually everything is already there. We just need to find out how to generate automated documentation from that?

Sharcoux commented 4 years ago

This might be enough? https://typedoc.org/

paulmelnikow commented 4 years ago

Have you found any projects that use it?