[4.x]: Long docblock comments for config fluent model setters

[khalwat]

What happened?

The Problem

The original pull request for adding fluent model methods to config classes had the same docblock comments for the fluent setter methods that the original properties have.

While this results in some duplication of comments, I found in my testing that this was the only way to deliver the DX of full documentation for the properties in the editor (I did try @see as well):

This was replaced with a 1 line description and the @see annotations, which results in a disparity between the long documentation you see for the properties, and a 1 liner for the fluent setter methods:

This makes it less useful, because the documentation is no longer easily available. In PhpStorm you then have to click on "See also" link, which unfortunately also does not render well:

Additionally, other editors such as VS Code don't handle @see links at all, so all you get is this:

The more documentation provided in situ, the better, imo. It seems consistent to have the properties and the setters both display the same documentation. Easier to keep them in sync, too.

The Resolution

Use the long comments from the original PR that match the docblock comments for the properties,

Craft CMS version

4.2.0

PHP version

n/a

Operating system and version

n/a

Database type and version

n/a

Image driver and version

n/a

Installed plugins and versions

n/a

[michaelrog]

I agree — The value prop of the original PR seems largely diminished here. 🤔

Also, I imagine that long-term, it'd actually be less work overall to keep the docblock contents identical between property and methods (less cognitive overhead, easier copy/paste), rather than to have to translate between two different styles/schemes.

[brandonkelly]

Brought the long descriptions back for the next release 😅