DocBlocks

[mrgoldy]

Lately I got a little irritated by docblocks throughout the code being rather inconsistent.
And I was wondering what your thoughts on them are.
With a final solution, I can start 'cleaning' them up if need be.

1. Should asterixes be indented with a space?
   In my opinion: Yes

   1. Code: Select all

      /**
      * A docblock
      */

   2. Code: Select all

      /**
       * A docblock
       */

2. Should there be an empty line before the @return tag
   In my opinion: No

   1. Code: Select all

      /**
       * @param string	$string
       * 
       * @return int
       */

   2. Code: Select all

      /**
       * @param string	$string
       * @return int
       */

3. Should variables and descriptions be aligned with eachother?
   In my opinion: Yes

   1. Code: Select all

      /**
       * @param string $string Some string description
       * @param int $number Some number description
       */

   2. Code: Select all

      /**
       * @param string	$string		Some string description
       * @param int		$number		Some number description
       */

4. Should use statements be added/used?
   In my opinion: Yes

   1. Code: Select all

      /**
       * @throws \phpbb\exception\runtime_exception 
       */

   2. Code: Select all

      use phpbb\exception\runetime_exception
      
      /**
       * @throws runtime_exception
       */

Long story short, every function should have a DocBlock which includes a short description and a @return tag.
And I feel like this is how a full DocBlock should look:

Code: Select all

/**
 * This is a short description of the function,
 * just a simple 1-2 liner.
 * 
 * If necessary, this is a longer / more extensive description.
 * With multiple lines
 * and perhaps even an example of two
 * 
 * @param int		$id		The identifier
 * @param string	$title		The title
 * @param array|false	$do_something	Whether or not we should do something
 * @return void
 * @throws runtime_exception
 *
 * @deprecated 3.3.0	(Removed: 4.0)	Instead use something_else, @see \some\class::something_else
 */

[david63]

Personally I do not like the indented asterisk

[mrgoldy]

Well, the thing is, it is even documented as such: https://docs.phpdoc.org/guides/docblocks.html
And most editors auto paste them like that, aswell as other repositories use this approach.

[david63]

Actually indenting by one space goes against phpBB coding guidelines where an indent should be four spaces

[3Di]

The coding guidelines need a rewamp.

And is even preferred to not stay buried in the past.

@see also: viewtopic.php?f=81&t=68156

[david63]

The coding guidelines need a rewamp.

That I would not disagree with

[AlfredoRamos]

I do not agree with point 2, personally I prefer adding an empty line just before @return, it's more readable for me that way, specially where you have more than 3 variables.

Personally I prefer something like:

Code: Select all

/**
 * This is a short description of the function,
 * just a simple 1-2 liner.
 * 
 * If necessary, this is a longer / more extensive description.
 * With multiple lines
 * and perhaps even an example of two
 *
 * @deprecated 3.3.0	(Removed: 4.0)	Instead use something_else, @see \some\class::something_else
 * 
 * @param int		$id		The identifier
 * @param string	$title		The title
 * @param array|false	$do_something	Whether or not we should do something
 *
 * @throws runtime_exception
 *
 * @return void
 */

In that order, with those empty new lines.

[3Di]

I do not agree with point 2, personally I prefer adding an empty line just before @return

Well, same here I can say.

Edit: what about @access etc.., seems like you all are missing it?

[hanakin]

I to like the gap before return. I agree on all others. That’s asi the standard I have been using for the js side.

[Marc]

I'm also for the gap to separate different types.

@3Di: The @access specifier is still a legacy from the old days when this couldn't be properly defined and is no longer needed (and therefore should also no longer be used).