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.
User avatar
mrgoldy
Registered User
Posts: 38
Joined: Fri Dec 18, 2015 9:41 pm
Location: The Netherlands
Contact:

DocBlocks

Post by 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
 */
phpBB Studio Proud member of the Studio!

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

Re: DocBlocks

Post by david63 »

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
mrgoldy
Registered User
Posts: 38
Joined: Fri Dec 18, 2015 9:41 pm
Location: The Netherlands
Contact:

Re: DocBlocks

Post by 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.
phpBB Studio Proud member of the Studio!

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

Re: DocBlocks

Post by david63 »

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: 772
Joined: Tue Nov 01, 2005 9:50 pm
Location: Milano (I) Frankfurt (D)
Contact:

Re: DocBlocks

Post by 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
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: 291
Joined: Mon Feb 07, 2005 7:23 am
Location: Lancashire, UK

Re: DocBlocks

Post by david63 »

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: 5
Joined: Wed Jul 02, 2014 9:44 pm

Re: DocBlocks

Post by AbaddonOrmuz »

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: 772
Joined: Tue Nov 01, 2005 9:50 pm
Location: Milano (I) Frankfurt (D)
Contact:

Re: DocBlocks

Post by 3Di »

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: 911
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: DocBlocks

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

User avatar
Marc
Development Team Leader
Development Team Leader
Posts: 155
Joined: Thu Sep 09, 2010 11:36 am
Location: Munich, Germany

Re: DocBlocks

Post by 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).

Post Reply