Fix comments longer than 80 characters

[ghost]

As per our documentation standards, comments should wrap at or before 80 characters. However there are quite a few places in core where comments run over the 80-character limit. This issue aims to fix that.

[ghost]

To find long comments lines, I'm using this Python script I wrote (I was bored one night): https://gist.github.com/BWPanda/163bbab64814f774881e7b770d51c8e0

[ghost]

Hmm, what to do about @code blocks whose code extends over 80 characters...? It's hard to wrap code nicely, for example:

 * @code
 * class views_handler_filter_node_type extends views_handler_filter_in_operator {
 *   function get_value_options() {
 *     if (!isset($this->value_options)) {
 *       $this->value_title = t('Node type');
 *       $types = node_get_types();
 *       foreach ($types as $type => $info) {
 *         $options[$type] = $info->name;
 *       }
 *       $this->value_options = $options;
 *     }
 *   }
 * }
 * @endcode

That line is 81 characters long. But putting the { on a new line doesn't seem right...
The standards for @code don't mention anything about line length. Perhaps we should decide on that and then update the standards...?

[indigoxela]

what to do about @ code blocks whose code extends over 80 characters

My personal opinion: As code itself can be longer, it should also be allowed to be longer inside @code elements.
Breaking the lines makes the code example less useful. People might think, the standard requires code to be written that way, or at least the example gets less readable.

[ghost]

Here's a PR that fixes comments in *.php files: backdrop/backdrop#3327

I purposefully didn't properly link it to this issue as I'd like this issue to stay open if/when the PR is merged, so we can work on other files too (e.g. *.module, *.inc, *.js, *.install, etc.).

[klonos]

My personal opinion: As code itself can be longer, it should also be allowed to be longer inside @code elements.

I agree 👍 ...URL links to documentation etc. included within comments should also be an exception, but only if they start at the beginning of the line (IOW a single URL that is more than 80 characters long itself).

Another issue with our comments is that some are much less than 80 characters long, but the first word on the next line fits in the current line. The most notable offenders are the Views and Views UI modules (see https://github.com/backdrop/backdrop/blob/1.x/core/modules/views/handlers/views_handler_area.inc#L11 for example). Not sure if you want to tackle that too next time you're bored @BWPanda (it will be tricky, but I know that you love puzzles/math 😅 ).

[ghost]

I agree that code shoudn't be wrapped, but that means we need to update the standards. I'll create a separate issue for that.