How to correctly wrap WordPress JavaScript documentation

The WordPress JavaScript documentation standards have an interesting section about line length. You should wrap your DocBlock text to the next line after 80 characters of text. The reason for this is to make code readable in any editor. Even if the editor doesn’t have a build-in wrapping mechanism. There is a simple way to wrap WordPress JavaScript documentation. I’ll show you how it works in this article.

Here’s the section about line length:

DocBlock text should wrap to the next line after 80 characters of text. If the DocBlock itself is indented on the left 20 character positions, the wrap could occur at position 100, but should not extend beyond a total of 120 characters wide.

Tools to align documentation

Most editors have guides that allow you to more easily wrap the right side of your lines. At Yoast most developers use PHPStorm. Since PHPstorm 2017.3 it has support for multiple guides. This makes it relatively easy to wrap the documentation in the correct column.

You can find the setting for multiple guides in Settings|Editor|Code Style|JavaScript|Wrapping and Braces|Visual guides. I put my guides at 80, 84, 88, 92, 96 and 120. The reason for this is that the majority of code is only indented with 1 to 4 tabs. Code that is indented with 5 tabs is scarce and is also could that should probably be refactored. The 120 is there to make sure I adhere to the absolute maximum.

How to wrap

You can use this as follows. The first step is finding out at which column you should be wrapping. Then you check if lines exceed this column. If so, you place a newline at the wrap column. Or before. So that the text never exceeds the wrap column. For example, if you have the following code snippet:

[js]
/**
* Toggles the quick edit window, hiding it when it’s active and showing it when inactive.
*
* @memberof inlineEditPost
* @since 2.7.0
*
* @param {Object} el Element within a post table row.
*/
toggle : function(el){
var t = this;
$( t.what + t.getId( el ) ).css( ‘display’ ) === ‘none’ ? t.revert() : t.edit( el );
},
[/js]

Because there is one tab of indentation this means that the wrapping should occur on the 84th column. We are assuming that one tab is equal to 4 spaces. The end result will be:

[js]

/**
* Toggles the quick edit window, hiding it when it’s active and showing it when
* inactive.
*
* @memberof inlineEditPost
* @since 2.7.0
*
* @param {Object} el Element within a post table row.
*/
toggle : function(el){
var t = this;
$( t.what + t.getId( el ) ).css( ‘display’ ) === ‘none’ ? t.revert() : t.edit( el );
},
[/js]

I hope this helps you with your documentation effort and wrapping adventures. Let me know if you use a different tool that can have multiple guides.

Read more: Why every website needs Yoast SEO »