Additional comment helpers.

[haringsrob]

• BC break? no

Hi,

This is a "long shot" and is currently incomplete in terms of support.

This pr adds additional comments to commentable types.

Prefix/suffix comment (both inline and wrap).

Reason for this is to have the ability to "wrap" certain functions with a start/end comment, which can then be used by other tools.

/** [some-attribute-before] */
/**
 * Original comment.
 */
function bar(): foo {}
/** [some-attribute-after] */

Inline comments can be useful for traits or variables

use App\Sometrait; // SomeComment

Let me know your idea's/suggestions.

ps. When all good, I will make sure there's tabs :D

[dg]

Hi, I don't find this feature useful and I don't really feel like adding it to the library. Can't you solve it in another way?

[haringsrob]

Hey @dg,

As far as I can see, within this library I cannot.

To provide some more context to why I am introducing this change:

We are building a package that helps with generating documentation for php based projects. For this we use torchlight.

We made a wrapper that uses this library to apply the torchlight docblocks to files/snippets

See https://github.com/area17/phptorch

[dg]

I understand. I think a better solution would be to parse the file with PhpParser (you can base it on the code of Nette\PhpGenerator\Extractor class) and find out the line numbers where classes, methods, imports etc start and end, and then add comments directly to the original file.

[haringsrob]

Hey @dg, I will check it out for sure, but I am afraid that we will then loose another small benefit which is the consistency we get in terms of formatting by this package.

Is there an alternative approach you would consider?

[dg]

Of course, a tool that adds inline comments to the source code can also add comments to the code produced by this library.