Documentation from Tests Roadmap

[alganet]

After working on better tests for Respect I've imagined some use cases for Respect\Doc that could be easy to implement.

The first is related to test method names and its meaning. Respect\Doc should be able to cover these cases:

Class: Respect\Rest\Router
Case: Respect\Rest\RouterTest
Method: staticRoute
Test: testStaticRoute
Meaning: Without even specifying @covers, Doc should be able to know that this test is about a method

Class: Respect\Rest\Router
Case: Respect\Rest\RouterTest
Method: staticRoute
Test: testItCanConstructStaticRoutesFromStrings
Meaning: Doc only know the method if @covers is specified, if not, the test is about the entire class behavior. It knows which this test is supposed to do as well because no method is matched. The @example tag could be used for displaying usage samples.

Class: Respect\Rest\Router
Case: Respect\Rest\RouterTest
Method: staticRoute
Test: testStaticRouteShouldAllowArrays
Meaning: Without even specifying @covers, Doc should be able to know that this test is about a method. It knows which this test is supposed to do as well by the Should keyword. This could be index on the specific section for this method. Doc could also use @example tags on the tests and display them on the generated documentation.

---

Grouping and linking documentation is also one of my goals. Tests with similar names (we should use levenshtein() or something like this) need to be grouped and sorted with meaning when listed on the single Markdown generated by Doc.

Related methods can be discovered by the @covers and @example tags. We should run text comparison between samples as well to try to identify similar samples and group these methods together as well.

[augustohp]

+1

[nickl-]

Clapping pandas === Happy pandas