Using {@inheritdoc} annotations

[pboivin]

Hi! I recently started exploring Doctum and it's fantastic. I'm really enjoying how easy it is to get started from the examples in the README.

Is there a way to use the {@inheritdoc} annotation with Doctum? I'm not sure if this is a bug or not implemented, and my apologies in advance if it's just a classic case of PEBKAC...

An example from the Laravel docs: Request::duplicate. You can see that the text {@inheritdoc} is used for the method description, instead of the inherited description.

[williamdes]

Hi @pboi20
Thank you for your very nice feedback!

Indeed this is implemented but there is probably some edge cases that where not well detected.
I will definitely have a look because this case is the basic one and it should work but there is something that's makes it not resolve.

https://github.com/laravel/framework/blob/306208394bf05f9acebce3663c3cfb7e3b1ac21c/src/Illuminate/Http/Request.php#L441

[pboivin]

Hi @williamdes, thanks for the quick reply!

I've been doing some more tests locally and I can confirm that {@inheritdoc} works within the context of my project. For example, Doctum is able to fetch the description for an overriden method from a parent class, if it's within my src directory.

However, it doesn't work for anything coming from the vendor directory. This makes sense, given my config.php:

$iterator = Finder::create()->files()->name('*.php')->in('./src');

I did a quick test using . instead of ./src and it worked! Doctum was able to fetch the description from a vendor package. This also makes sense. Unfortunately, all vendor packages ended up in the Doctum output, which is not very desirable.

Just curious to know if this makes sense from your perspective. The example from the Laravel codebase (above) also pulls from a vendor package: Symfony\Component\HttpFoundation\Request

[williamdes]

This also makes sense. Unfortunately, all vendor packages ended up in the Doctum output, which is not very desirable.

Yes, this is why I think this situation can not really be solved because the user did not give access to Doctum to the necessary source classes.

This also is problematic for class type hints, as soon as they are out of the scope of the analysed files we can not show a link to the file/class.

Thank you so much for the quick research, that saved me some debug hours :)

If you have a smart idea to solve this let me know ;)

[pboivin]

Just brainstorming here — Would it be possible to add a configuration option to include 'vendor' packages in Doctum's analysis, but not in the final API documentation tree view? In terms of configuration, here's roughly what I have in mind:

$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->in('./src');

$vendor_iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->in('./vendor/some-package')
    ->in('./vendor/other-package');
    /* ... */

return new Doctum($iterator, [
    'vendor' => $vendor_iterator,
    /* ... */
]);

This way, Doctum could pull the necessary annotations form specific vendor packages but keep the documentation cleanly focused on the scope of the project.

Curious to know if that's worth exploring :)

[williamdes]

Hi !

This would make sense, also would have some cost to process all files but is possible to do. That would allow inheritdoc to work correctly