update Programmatic API documentation

[boneskull]

From @boneskull on July 12, 2015 4:13

from #1298

There is very little information that explains how to use the programmatic interface. All that is really mentioned is this wiki page that provides an example. It would be nice to see explicitly what is available like this (for example).

Copied from original issue: mochajs/old-mochajs-site#6

[boneskull]

From @cloakedninjas on October 16, 2015 10:59

👍

[dfberry]

I've read #3140, the only API doc page, and the CLI versus API perspective. What are you hoping for in new/more docs for the API?

[v-geberr]

@boneskull Any insight here?

[boneskull]

Ideally:

• We would generate some documentation from the docstrings in the codebase with documentation or a like tool
• Update those docstrings if necessary
• Provide tutorials for
  • Writing a custom reporter
  • Writing a custom interface
  • Running Mocha programmatically through its API (with a pragmatic use case)
• All of this should live in docs/ somewhere and linked to from the main page.
  For now, since mochajs.org only has a single page, this necessarily may need some decisions around styling, but a logo and default theme would work with the API docs. The tutorial can just pull in the styles from the main page, I guess.
• The wiki page should probably be removed and links to the new content put in as its replacement

(Are you @dfberry or @v-geberr? I was going to give credit in the CHANGELOG with v5.0.0)

[boneskull]

(The tutorials can be a separate effort, but at minimum we will need API docs generated)

[dfberry]

Hi @boneskull,
@dfberry is the correct account. The @v-geberr is my work account -- sorry about that confusion -- I'll be more consistent moving forward.

Thank you for the direction. Can you assign this to me? Or how do I do it?

[dfberry]

@boneskull I have a rough draft of the API doc generated from documentationjs here. I pulled everything that was labeled public or that I thought was public. There relationships are only there for the reporters not the project as a whole. Can you look it over and give feedback?

[OSP123]

@dfberry Would love to see that API doc, but getting 404. Any way that can be made public?

[k3n]

Also wishing there was more documentation.

My use case: I'd like to take a group of directories, and add each directory as a Suite (obviously containing the tests inside).

I can add each of the files independently using Mocha#addFile, and I can create a Suite, but Suite only provides a Suite#addTest which expects a Test object created from a function. I don't know how to transform a test file into a function that it expects. I'm pretty sure I can figure it out in a few more hours, but it sure would be nice to not have to deconstruct the source to figure that out (and to be sure I do it correctly).