Add PHPDoc blocks to AbstractMigration

[koninka]

Q	A
Type	improvement
BC Break	no
Fixed issues

Summary

Add PHPDoc blocks to AbstractMigration methods. This could be useful for those who use @inheritdocannotation (like me:)).

[greg0ire]

Why would it be useful?

[koninka]

@greg0ire

Hey,

1. It's good practice to document your code.
2. Having a description for the methods makes it easy to understand what they do. For example, the write and warnIf methods are not immediately obvious without additional code reading (not only in the AbstractMigration class).
3. My case. I always document my code and use @inheritdoc for overridden vendor methods (e.g. getDescription). And if I use @inheritdoc and parent method has no phpdocs, then this is at least strange (also PHPStorm reports warning).

You have a description of the methods on the site, why not place the documentation in the code to save programmers from the need to google or research the code in depth to understand its work?

[greg0ire]

1. It is, but documentation has to bring value, otherwise you risk people not reading useful comment because most comments in your project are just noise. I'd argue that's the case of most comments in this PR.
2. That's the part of the PR that might bring some value. If I were to merge anything here, that would be it.
3. That's really personal, sorry but we are not going to pollute the code with tautological comments. If you want to add comments, they should bring value.

You have a description of the methods on the site, why not place the documentation in the code to save programmers from the need to google or research the code in depth to understand its work?

That's a good point, maybe there is valuable information here that could be fit in the comments. Description of this migration is not valuable information IMO. So is information already contained in type declarations.

[koninka]

@greg0ire

I got it. So, do I understand correctly, if I add a more useful description for the getDescription, then you will merge pr? Do I need to add a more detailed description to other methods?

P.S. I took a description of all methods from the official site (for method getDescription too).

[greg0ire]

Tautological, either improve or remove

[koninka]

Fixed

[greg0ire]

Nothing new here, let's remove it

Suggested change

	*
	* @return string

[koninka]

Fixed

[greg0ire]

Suggested change

	*
	* @param bool $condition
	* @param string $message

[koninka]

Fixed

[greg0ire]

That's made fairly clear just by reading the signature (you don't have to read the code inside the method)

[koninka]

Fixed

[greg0ire]

debug information is written with debug(), this is a notice.

[koninka]

Fixed

[greg0ire]

Suggested change

	*
	* @param string $message

[koninka]

Fixed

[greg0ire]

Please revert this.

[koninka]

Fixed

[greg0ire]

So, do I understand correctly, if I add a more useful description for the getDescription, then you will merge pr?

It's the opposite actually, if we merge the PR, then it means you will have added a more useful description for that method, but that will probably not be enough, since other methods need a better description too.

[greg0ire]

Suggested change

	/**
	* Description of this migration.
	*
	* Describe what this migration does in simple terms. This information is displayed when you view the list of migrations.
	*/
	/**
	* Describe what this migration does in simple terms. This information is displayed when you view the list of migrations.
	*/

[greg0ire]

🤔 I mean it should, but it's actually written with notice(), so that comment is just misleading