Automating documentation of Rule Sets

[peterfox]

I'm finding over at Laravel Rector that we have more use for sets as a repository based around a framework. We'll need to start documenting sets more to add value to those wanting to start using them with Rector. That said there's no automated mechanism to document the set as there is to document rules.

I thought it might be a good idea to bring up the topic here as it could be useful for all Rector based repos.

My idea is keeping it simple such as using attributes for the \Closures returned by sets.

return #Attribute[new RuleSetDocumentation('Laravel 5.0', 'Rules to upgrade projects to Laravel 5.0')] static function (RectorConfig $rectorConfig): void {
    $rectorConfig->import(__DIR__ . '/../config.php');

    // https://stackoverflow.com/a/24949656/1348344
    $rectorConfig
        ->ruleWithConfiguration(RenameClassRector::class, [
            'Illuminate\Cache\CacheManager' => 'Illuminate\Contracts\Cache\Repository',
            'Illuminate\Database\Eloquent\SoftDeletingTrait' => 'Illuminate\Database\Eloquent\SoftDeletes',
        ]);

    $rectorConfig
        ->ruleWithConfiguration(
            RenameMethodRector::class,
            [new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'links', 'render'),
                new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getFrom', 'firstItem'),
                new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getTo', 'lastItem'),
                new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getPerPage', 'perPage'),
                new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getCurrentPage', 'currentPage'),
                new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getLastPage', 'lastPage'),
                new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getTotal', 'total'),
            ]
        );
};

My other idea would be to start returning anonymous class invokables instead of \Closures that could implement and interface to describe the set.

return new class() implements RectorSetDocumentation {
  public function documentation(): SetDefinition
  {
    return new SetDefinition('Laravel 5.0', 'Rules to upgrade projects to Laravel 5.0');
  }

  public function __invoke(RectorConfig $rectorConfig): void
  {
      $rectorConfig->import(__DIR__ . '/../config.php');
  
      // https://stackoverflow.com/a/24949656/1348344
      $rectorConfig
          ->ruleWithConfiguration(RenameClassRector::class, [
              'Illuminate\Cache\CacheManager' => 'Illuminate\Contracts\Cache\Repository',
              'Illuminate\Database\Eloquent\SoftDeletingTrait' => 'Illuminate\Database\Eloquent\SoftDeletes',
          ]);
  
      $rectorConfig
          ->ruleWithConfiguration(
              RenameMethodRector::class,
              [new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'links', 'render'),
                  new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getFrom', 'firstItem'),
                  new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getTo', 'lastItem'),
                  new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getPerPage', 'perPage'),
                  new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getCurrentPage', 'currentPage'),
                  new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getLastPage', 'lastPage'),
                  new MethodCallRename('Illuminate\Contracts\Pagination\Paginator', 'getTotal', 'total'),
              ]
          );
  }
}

Then it would just be a case of scanning certain folders to generate the documentation into a markdown document in a similar way to how the rules are.

Was curious of the community's thoughts?

[TomasVotruba]

I like the attribute approach. Simple, clear and easy to implement 👍
Do you have POC somewhere? I'd love to see it 🔥

[peterfox]

No, not yet. But it seems simple enough to take on. Wanted to float the idea first. 😄