DocBlocks

General discussion of development ideas and the approaches taken in the 3.x branch of phpBB. The next feature release of phpBB 3 will be 3.3/Proteus.
Forum rules
Please do not post support questions regarding installing, updating, or upgrading phpBB 3.2.x. If you need support for phpBB 3.2.x please visit the 3.2.x Support Forum on phpbb.com.

If you have questions regarding writing extensions please post in Extension Writers Discussion to receive proper guidance from our staff and community.
Post Reply
User avatar
posey
Registered User
Posts: 34
Joined: Fri Dec 18, 2015 9:41 pm

DocBlocks

Post by posey » Wed Aug 28, 2019 6:23 pm

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
 */
Better known as mrgoldy.

User avatar
david63
Registered User
Posts: 278
Joined: Mon Feb 07, 2005 7:23 am
Location: Lancashire, UK

Re: DocBlocks

Post by david63 » Wed Aug 28, 2019 7:40 pm

Personally I do not like the indented asterisk
David
Remember: You only know what you know -
and you do not know what you do not know!

User avatar
posey
Registered User
Posts: 34
Joined: Fri Dec 18, 2015 9:41 pm

Re: DocBlocks

Post by posey » Wed Aug 28, 2019 8:12 pm

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.
Better known as mrgoldy.

User avatar
david63
Registered User
Posts: 278
Joined: Mon Feb 07, 2005 7:23 am
Location: Lancashire, UK

Re: DocBlocks

Post by david63 » Wed Aug 28, 2019 8:29 pm

Actually indenting by one space goes against phpBB coding guidelines where an indent should be four spaces
David
Remember: You only know what you know -
and you do not know what you do not know!

User avatar
3Di
Registered User
Posts: 762
Joined: Tue Nov 01, 2005 9:50 pm
Location: Milano (I) Frankfurt (D)
Contact:

Re: DocBlocks

Post by 3Di » Wed Aug 28, 2019 8:54 pm

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
Please PM me only to request paid works. Thx.
Want to compensate me for my interest? Donate
My development's activity º PhpStorm's proud user
Extensions, Scripts, MOD porting, Update/Upgrades
👨‍🏫 | Take a tour to | The Studio | 👨‍🏫

User avatar
david63
Registered User
Posts: 278
Joined: Mon Feb 07, 2005 7:23 am
Location: Lancashire, UK

Re: DocBlocks

Post by david63 » Wed Aug 28, 2019 9:10 pm

3Di wrote:
Wed Aug 28, 2019 8:54 pm
The coding guidelines need a rewamp.
That I would not disagree with
David
Remember: You only know what you know -
and you do not know what you do not know!

User avatar
AbaddonOrmuz
Registered User
Posts: 4
Joined: Wed Jul 02, 2014 9:44 pm

Re: DocBlocks

Post by AbaddonOrmuz » Thu Aug 29, 2019 7:05 pm

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.

User avatar
3Di
Registered User
Posts: 762
Joined: Tue Nov 01, 2005 9:50 pm
Location: Milano (I) Frankfurt (D)
Contact:

Re: DocBlocks

Post by 3Di » Thu Aug 29, 2019 10:58 pm

AbaddonOrmuz wrote:
Thu Aug 29, 2019 7:05 pm
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?
Please PM me only to request paid works. Thx.
Want to compensate me for my interest? Donate
My development's activity º PhpStorm's proud user
Extensions, Scripts, MOD porting, Update/Upgrades
👨‍🏫 | Take a tour to | The Studio | 👨‍🏫

User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 906
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: DocBlocks

Post by hanakin » Sun Sep 08, 2019 11:54 am

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.
Donations welcome via Paypal Image

Post Reply