Php-cs-fixer: Header comment

[sharifzadesina]

Hi
Due to PSR 5 (PHPDoc standard) header comments or file level comments should start with double star /** not single star /*, so other non-standard comments can start with single star /*.

For example:

<?php

/**
 * This is our header comment or file level comment
 */

/*
 * This is for describe coming codes
 */

$foo = 'bar';

/*
 * This is for describe coming codes
 */

$bar = 'foo';

[sharifzadesina]

at the other hand you should check Structural Elements and prevent replacing header comment.

for example:

<?php

[YOU SHOULD ADD HEADER COMMENT HERE]

/**
 * YOU SHOULD NOT REPLACE THIS
 */
include 'test'; // because include is structural element

<?php

/**
 * YOU SHOULD REPLACE THIS
 */
testFunc();

<?php

[YOU SHOULD ADD HEADER COMMENT HERE]

/*
 * YOU SHOULD NOT REPLACE THIS
 */
$foo = 'bar';

<?php

/**
 * YOU SHOULD REPLACE THIS
 */

/**
 * YOU SHOULD NOT REPLACE THIS
 */
include 'test'; // because include is structural element

tnx

[soullivaneuh]

The PSR-5 seems to be on the proposed section. Are we sure this one will be accepted?

[SpacePossum]

this is addressed in two PR's, latest open for review is https://github.com/FriendsOfPHP/PHP-CS-Fixer/pull/1949
so please give me feedback ;)

[GrahamCampbell]

Header comment

It's called header comment for a reason. Because it's meant to be a comment. What you're proposing is not a comment, it's phpdoc.

[SpacePossum]

What you're proposing is not a comment, it's phpdoc.

indeed, that is why I called the configuration option phpdoc

[GrahamCampbell]

It is specifically called a header comment. I don't think we should allow configuration.

Even if we did, it still wouldn't work, because our other fixers would remove the blank line after it, or convert it back to a comment.

[SpacePossum]

It is specifically called a header comment. I don't think we should allow configuration.

I think we should, there is no standard to not allow it.

Even if we did, it still wouldn't work, because our other fixers would remove the blank line after it, or convert it back to a comment.

Those fixers can be configured to ran or not so it is not an issue. I would like to see the PHPDoc to comment fixer fixed though, but it is not an requirement as people can switch the fixer off.

[GrahamCampbell]

Those fixers can be configured to ran or not so it is not an issue.

It is definitely an issue. The tool will go back and forward on each run.

[SpacePossum]

It is definitely an issue. The tool will go back and forward on each run.

Nope, switched off the fixer and all good.
There are more conflicting fixers, it should not stop development. The PHPDoc to comment one can be fixed to be none-conflicting btw.

[sharifzadesina]

@GrahamCampbell
This project's header comment is same as PHP PSR standard's file level comment so it is better to us following standards or add support for standards.

[sharifzadesina]

@Soullivaneuh We need this change, while accepted or not (of course it is more likely to be accepted)

[soullivaneuh]

We need this change, while accepted or not

Accepted PSR or not is important, whatever your needs.

If this PSR will be accepted, this should be added to the related preset IMHO.

If not, this may be in contrib, if accepted on this project.

[sharifzadesina]

@Soullivaneuh I think for now It is better to implement this in phpdoc.

[soullivaneuh]

That's you say! :wink: Without why BTW.

And apparently the proposed PSR, this is why I would like to know if this is gonna be accepted or not.

IMHO, the fixer might be accepted, but the preset would change regarding the PSR acceptance.

[soullivaneuh]

Related PSR PR: https://github.com/php-fig/fig-standards/pull/169

[SpacePossum]

PSR5 does not state a file level comment _must_ be PHPDoc, only that if it is a PHPDoc how it should look.

[GrahamCampbell]

Yeh, well, I don't agree, and PSR is not the law. Saying a comment must be phpdoc is a contradiction.

[SpacePossum]

I'll try again :)
PSR5 doesn't state there _must_ be a PHPDoc as a header of the file, so a comment is allowed.

[soullivaneuh]

Yeh, well, I don't agree, and PSR is not the law. Saying a comment must be phpdoc is a contradiction.

Agree with @GrahamCampbell. This is a comment, a signature. How this could be a phpdoc?

PSR5 doesn't state there must be a PHPDoc as a header of the file, so a comment is allowed.

So you need the fixer to be able to handle both. Maybe you are right. I am personally not against a fixer like this.

The only thing that I would like to add a warning, is the group placement. The PSR-5 is not accepted yet, so IMHO the fixer (or option of the existing) should be put on contrib group.

After that, I'm not the project owner, this is just an opinion. :wink:

[sharifzadesina]

@GrahamCampbell PSR IS LAW for many developers so we MUST support that at first then invent new standards.

[soullivaneuh]

PSR IS LAW for many developer

Is a convention. I like this convention and you are right, many developers follow it. But it's a convention.

so we MUST support that at first then invent new standards.

We can support the rule. But IMO not create a PSR-5 section, for now.

Except if PHP-CS-Fixer maintainers don't think like this.

@SpacePossum PSR5 state this, see my links in first issues's post.

And PSR-5 is AFAIK not accepted yet: https://github.com/php-fig/fig-standards/pull/169

So, to resume: Nobody says (stop me if I'm wrong) we should not add your rules. For me, the only thing is not correct is to tell this is PSR until the proposed rule is not accepted by php-fig.

[soullivaneuh]

To make everybody agree, we can think to add a two_stars or phpdoc_style option to the header_comment fixer.

False by default to be BC.

[sharifzadesina]

To make everybody agree, we can think to add a two_stars or phpdoc_style option to the header_comment fixer.

I agree, This is most fastest way for now.

[gharlan]

-> #1297

[SpacePossum]

To make everybody agree, we can think to add a two_stars or phpdoc_style option to the header_comment fixer.

False by default to be BC.

...

this is addressed in two PR's, latest open for review is #1949 (https://github.com/FriendsOfPHP/PHP-CS-Fixer/issues/1987#issuecomment-225494365)

1949 replaces 1297, both provide just that.

;)

[soullivaneuh]

@SpacePossum I know that. At first, I just added a remark about not accepted PSR-5, nothing else... :wink:

[GrahamCampbell]

@sharifzadesina This is not even PSR though...

[SpacePossum]

This is going in circles. I hear no new arguments and I'm not convinced to change the PR.
So lets put up to vote. If it doesn't make the vote I throw the PR away and someone else can do the strict declare stuff and we call it a day.

[keradus]

big :+1: for allowing header to be both comment or PHPDoc, depending on configuration.
If it needs some adjustment for PHPDoc classes or other fixers to properly deal with it - it's OK to do it.

@SpacePossum , sorry, I was confused about changing header fixer in PR introducing strict fixer

[keradus]

Closing due to merge of #1949