API documentation

[gaspard]

I am having a very difficult time using vexflow due to either me not finding the proper location for the API documentation or maybe these docs are missing.

Just having an API wiki specifying function arguments would be a huge help...

For example, I cannot find documentation on

1. note durations (from a number representing a fraction of a whole note)
2. creating rests

[lpeppe]

I had your same problem when I started using vexflow. The way I solved it was to use PHPStorm and open the vexflow-debug.js in the structure view. In this way you can see all the VexFlow classes and methods.
As for your 2 problems:

1. the note durations are (in order) w, h, q, 8, 16
2. to create a rest you just need to add a "r" at the end of the duration. For example wr is a whole rest, hr is a half rest and so on

[SalahAdDin]

Yes, @gaspard i'm agreed with you.

[gristow]

Duplicate of #513 -- and you're absolutely right. We could definitely use help in providing clearer documentation for VexFlow's API. As you come across gotchas like you did in #531, if you think to document them in the wiki it'll forever help future VexFlow users!

[tmcw]

I'd be happy to adopt this task, if there's interest on the developers part, and implement automated API documentation.

[SalahAdDin]

@tmcw Please!

[gristow]

Yes, @tmcw, that would be wonderful. A great place to start might be creating documentation for the major classes, documenting especially the properties available on the various options objects.

Given the wide support that JSDoc now has (in particular, WebStorm & VSCode do a great job of tracking types & properties from JSDoc), I wonder if it's time we move in that direction instead of Docco. @0xfe do you have any objection to moving towards JSDoc?

Some code commenting is already close to correct JSDoc -- tuplet.js for instance just needs to have the parameters of the options object reformatted to something like this:

/**
 * @param {object} options
 * @param {number} options.num_notes fit this many notes into...
 * @param {number} options.notes_occupied ...the space of this many notes
 */

Other classes will need much more attention to document all of their properties.

[loganknecht]

Bumping this because I have spent some time looking for API documentation and have not had success. The API link in the wiki directs me to a page that is not super helpful.

Please keep up the great work though! This is an incredibly impressive library and I love how much the community is working together to advance and maintain this!

[SalahAdDin]

@tmcw please man.

[srad]

Is this settled yet? I don't know how people use this library at all beyond the examples.

The only thing needed are the parameter doc for each method call.

The API doc linked on the site somewhere, is also strange and doesn't show all links to subpages, since the list doesn't expand properly (once you have figured out you need to hover the symbol at the top)...

Is there some documentation on the parameters for the method calls?

[rvilarl]

Hi all, I am updating / doing documentation using typedoc, help would be appreciated.

@0xfe As I said somewhere else, it would make sense to release a version 4.0.0a to provide visibility on the documentation and the typescript approach.

[rvilarl]

@ronyeh this belongs to 4.0.0, the basis is there then we will have to go on specifc topics, please label.

[ronyeh]

I agree that API docs and general "how to use" docs are super important for increasing adoption of VexFlow.

As we get the 4.0 release ready, we need to prioritize this.