Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add RequireOneLineDocComment sniff #252

Merged
merged 1 commit into from May 10, 2021
Merged

Conversation

simPod
Copy link
Contributor

@simPod simPod commented May 7, 2021

This reduces vertical space in code. Same as it's already done for @var annotations as

/**
 * @var mixed
 */
/** @var mixed */

is now done for other annotations

/**
 * @param mixed $param
 */
/** @param mixed $param */

This reduces vertical space in code. Same as it's already done for `@var` annotations as

```php
/**
 * @var mixed
 */
```

```php
/** @var mixed */
```

is now done for other annotations

```php
/**
 * @param mixed $param
 */
```

```php
/** @param mixed $param */
```
@simPod simPod requested a review from a team as a code owner May 7, 2021 08:57
malarzm
malarzm previously requested changes May 7, 2021
Copy link
Member

@malarzm malarzm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm 👎 , the expected life of a @var comment is to eventually disappear superseded by typed properties, it has almost no chances to be expanded. Method comments on the other hand might see an additional @throws or an explanation added which would then "unwind" single-lined /** @parameter */. This will likely lead to different styles of comments in same file and bigger diffs (currently +1/0 vs proposed +4/-1 for adding a @throws)

@Ocramius
Copy link
Member

Ocramius commented May 7, 2021 via email

@ostrolucky
Copy link
Member

@malarzm you still can't and won't be able to replace @var array<string, stdClass> for a long time

@malarzm
Copy link
Member

malarzm commented May 8, 2021

@ostrolucky yeah I know,but that doesn't change a thing :) @var still won't have anything more added to it so each and every @var will be inlined.

@simPod
Copy link
Contributor Author

simPod commented May 10, 2021

@malarzm I'm using doctrine orm and jms-serializer in some projects. Both require their @annotations so it multilines @var declarations here and there. Comments are another example.

With PHP language development those annotations are slowly disappearing as it's getting replaced by native features. Having only a single one in a single doc block is becoming more and more frequent (almost everything except generics and advanced types is gone).
Diff change size seems insignificant 🤔

@malarzm
Copy link
Member

malarzm commented May 10, 2021

'm using doctrine orm and jms-serializer in some projects. Both require their @annotations so it multilines @var declarations here and there.

Yeah but that means all (or a great majority) of comments are not inlined hence consistent across the file. IMO it'll be much harder with methods.

Anyway my vote currently doesn't change a thing :)

@Ocramius
Copy link
Member

This should've gone to the next major: all downstream projects are broken in a patch upgrade.

@greg0ire
Copy link
Member

On it: #284

And I think I should write a contributing guide for this specific repository, because that's not the first time this happens.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

7 participants