Contrib.social

Standardize on indent and comment line length within code samples in a docblock (@code … @endcode)

Open on Drupal.org →
Created on 11 July 2012, almost 13 years ago
Updated 18 February 2025, 3 months ago

Two small things that I was not clear on when adding my first code sample to a docblock:

Under "General documentation standards" in the Doxygen and comment formatting conventions, it's indicated that there is an exception for comment line length within @code blocks, but the exception is not explained further down. Should the comment length still wrap to 80 chars or should the comment wrap at 80 chars relative to the code sample? This is not consistent in core so I'm not sure if there is a well-documented standard for this. My thinking is that comments within a @code block could be 80 chars relative to the code, so that when the code is displayed on api.drupal.org or elsewhere it matches our standards, but either way works.

Also, in the example code sample given, the code is indented one level from the @code … @endcode, but this is not consistent throughout core so I'm not sure if that has been standardized or not.

📌 Task
Status

Active

Component

Documentation

Created by

🇨🇦Canada star-szr

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024