Ordering classes inside a group

emilianotisato commented 4 years ago

Idea When writing a documentation, order of the concepts explained are important for the readers. For example in an API documentation it has not sense to show first how user profile is fetched if you did't explain API authentication first for that user to reach his profile in the first place.

Current status Today we can order groups correctly because the items inside the array modules key in enlighten config file are respected. Then you can order methods because the order of those methods inside a given test class are respected to.

But there is a missing "element" to order in the documentation, that is the classes inside a Group.

Solution 1 - regex capturing groups orderd We maybe can respect the order of the regex capturing groups. Right now if we have this key inside 'modules' (enlighten config file):

       [
            'name' => 'Shows',
            'pattern' => ['*Show*', '*Episode*', '*FavoriteShows*']
        ],

They are ordered alphabetically: EpisodesControllerTest, FavoriteShowsControllerTest and ShowsControllerTest, but the ideal will be to respect the order of the patterns (capturing groups in regex) so user is in control of the end result.

Solution 2 - new @order annotations for test class level It maybe a solution to add a @order annotation to be respected when documentation is build.

// ShowsControllerTest.php
/**
* @group 1
* @testdox Working with shows
*/
class ShowsControllerTest extends TestCase 
{
// 
}

// EpisodesControllerTest.php
/**
* @group 2
*/
class EpisodesControllerTest extends TestCase 
{
// 
}

// FavoriteShowsControllerTest.php
/**
* @group 3
* @testdox Users can favorite shows
*/
class FavoriteShowsControllerTest extends TestCase 
{
// 
}

sileence commented 4 years ago

@emilianotisato thanks for posting this issue. I like the idea of a new annotation, for example:

@enlighten {"order": 3"}

This will add a new column in the example_groups table (i.e. order_num) and we can use that to sort the classes, like so:

orderBy('order_num')->orderBy('class_name')

emilianotisato commented 4 years ago

Sounds useful!!

jeffochoa commented 4 years ago

Closing this one now, the @enlighten {"order": 3"} annotation is available on version 5.0.1 🎉

StydeNet / enlighten

Ordering classes inside a group #37