Jump to content
interrobang

Better PHPDoc Comments in PW Classes

Recommended Posts

I would like to see some more usage of PHPDoc comments.

As a quick test I modified the Page class to include @property comments for all the magic properties, and it works great so far. My IDE now doesn't show warnings for things like $page->name and even gives me autocompletion.

I think it would quite useful to include something like this for all the classes also listed in the cheatsheet. What do you think about it? Btw, my IDE is PHPStorm.

This is how my Page.php header now looks like:

EDIT: Updated the code example to include the cheatsheet comments:

/**
* ProcessWire Page
*
* Page is the class used by all instantiated pages and it provides functionality for:
*
* 1. Providing get/set access to the Page's properties
* 2. Accessing the related hierarchy of pages (i.e. parents, children, sibling pages)
*
* ProcessWire 2.x
* Copyright (C) 2010 by Ryan Cramer
* Licensed under GNU/GPL v2, see LICENSE.TXT
*
* http://www.processwire.com
* http://www.ryancramer.com
*
* @property int		 $id		   The numbered ID of the current page
* @property string	  $name		 The name assigned to the page, as it appears in the URL
* @property string	  $title		The page's title (headline) text
* @property string	  $path		 The page's URL path from the homepage (i.e. /about/staff/ryan/)
* @property string	  $url		  The page's URL path from the server's document root (may be the same as the $page->path)
* @property string	  $httpUrl	  Same as $page->url, except includes protocol (http or https) and hostname.
* @property Page		$parent	   The parent Page object or a NullPage if there is no parent.
* @property int		 $parent_id	The numbered ID of the parent page or 0 if none.
* @property PageArray   $parents	  All the parent pages down to the root (homepage). Returns a PageArray.
* @property Page		$rootParent   The parent page closest to the homepage (typically used for identifying a section)
* @property Template	$template	 The Template object this page is using
* @property FieldsArray $fields	   All the Fields assigned to this page (via it's template, same as $page->template->fields). Returns a FieldsArray.
* @property int		 $numChildren  The number of children (subpages) this page has.
* @property PageArray   $children	 All the children (subpages) of this page.* Returns a PageArray. See also $page->children($selector).
* @property Page		$child		The first child of this page. Returns a Page. See also $page->child($selector).
* @property PageArray   $siblings	 All the sibling pages of this page.† Returns a PageArray. See also $page->siblings($selector).
* @property Page		$next		 This page's next sibling page, or NullPage if it is the last sibling.† See also $page->next($pageArray).
* @property Page		$prev		 This page's previous sibling page, or NullPage if it is the first sibling.† See also $page->prev($pageArray).
* @property string	  $created	  Unix timestamp of when the page was created
* @property string	  $modified	 Unix timestamp of when the page was last modified
* @property User		$createdUser  The user that created this page. Returns a User or a NullUser.
* @property User		$modifiedUser The user that last modified this page. Returns a User or a NullUser.
* @method string render() Returns rendered page markup. echo $page->render()
*/
class Page extends WireData {
...

post-560-0-08314600-1342020179_thumb.png post-560-0-20639200-1342020224_thumb.png

Share this post


Link to post
Share on other sites

It seems there isnt't very much interest in this. :(

Anyhow, Ryan, would you merge phpdocs like this example into you code if I send you a pull request on github?

Share this post


Link to post
Share on other sites

I think this is a really good idea as it will help to adopt PW among PHP developers who use IDEs in their work (such as NetBeans, PHPStorm, Eclipse etc.). As a side effect it can potentially make more people here use IDE. Autocompletion is addictive :)

Share this post


Link to post
Share on other sites

It all sounds good to me. I'm not against it. Though I don't use PHPDoc or any editor that supports it, so the comments you see in the code have always been for my reference (though I think the style is similar to PHPDoc). I'll be honest, I just can't think in code when I'm surrounded by a IDE that has lots to look at and is trying to do stuff for me. So I stick to VIM, full screen. :)

I haven't figured out how to bring in a pull request without files getting deleted or tabs/linebreaks getting screwed up, so I'd prefer to just make any changes here manually. It sounds like what you are wanting is a @property tag for the class properties in Page.php? I'm happy to do this, but have a concern: most of these properties are not API accessible. You don't want these showing up in your IDE unless you are modifying or extending the Page class (which nobody has done yet as far as I know).

Likewise, I think we need to be careful with phpdoc for any PW class properties if the intention is to have them show in your IDE. The reason for this is that the vast majority of API accessible properties are handled through PHP magic methods and not actually properties of the classes themselves. If you use the properties of the classes, you'd be getting an very incorrect view of the API.

On the other hand, PHPDoc should be totally fine for public functions. Though there are many public functions that are not part of the public API (meaning, PW classes use them internally, but you shouldn't), so relying on an IDE for this stuff would again give an incorrect view of the API that could get one into trouble. I think it's better to use the cheatsheet and PW API documentation for this stuff. Though maybe there are also some phpdoc tags that can help clarify if a public function is for internal (core use).

Share this post


Link to post
Share on other sites

It all sounds good to me. I'm not against it. Though I don't use PHPDoc or any editor that supports it, so the comments you see in the code have always been for my reference (though I think the style is similar to PHPDoc). I'll be honest, I just can't think in code when I'm surrounded by a IDE that has lots to look at and is trying to do stuff for me. So I stick to VIM, full screen. :)

You can work in fullscreen in PhpStorm, too. :) But I think a IDE is for advanced programmers like yourself of less use. I only know some PHP basics and I think a IDE can help me a lot to write better code in less time.

It sounds like what you are wanting is a @property tag for the class properties in Page.php? I'm happy to do this, but have a concern: most of these properties are not API accessible. You don't want these showing up in your IDE unless you are modifying or extending the Page class (which nobody has done yet as far as I know).

I want to add all properties and methods which are currently invisible because they are called via magic methods but are listed in the Cheatsheet. Basically I want the Cheatsheet available in my IDE ;)

I think I dont understand what you you are saying about most properties are not API accessible.

Likewise, I think we need to be careful with phpdoc for any PW class properties if the intention is to have them show in your IDE. The reason for this is that the vast majority of API accessible properties are handled through PHP magic methods and not actually properties of the classes themselves. If you use the properties of the classes, you'd be getting an very incorrect view of the API.

On the other hand, PHPDoc should be totally fine for public functions. Though there are many public functions that are not part of the public API (meaning, PW classes use them internally, but you shouldn't), so relying on an IDE for this stuff would again give an incorrect view of the API that could get one into trouble. I think it's better to use the cheatsheet and PW API documentation for this stuff. Though maybe there are also some phpdoc tags that can help clarify if a public function is for internal (core use).

My IDE shows basically the same information as the APIGen documentation. I think there is no need to add better comments to the public methods. Yours work quite well in my IDE. If you are really concerned that we can see public functions that are not part of the public API you can maybe add a @access private or a @internal tag?

The offical purpose of the @propery and @method tags is to add documentation for "magic" properties and methods. So I don't think we get a incorrect view of the API.

See here: http://manual.phpdoc...operty.pkg.html http://manual.phpdoc...method.pkg.html

I haven't completed the phpdoc-comments for all classes yet, but the most important classes are ready:

https://github.com/b...f073ad2ea97d03a

Share this post


Link to post
Share on other sites
The offical purpose of the @propery and @method tags is to add documentation for "magic" properties and methods. So I don't think we get a incorrect view of the API.

Thanks, this is what I was looking for. This answers my concern.

If you are really concerned that we can see public functions that are not part of the public API you can maybe add a @access private or a @internal tag?

@internal sounds like what we need!

I will put this on my to-do list.

Thanks,

Ryan

Share this post


Link to post
Share on other sites

Sure, if it's not any trouble that'd be great. I tend to make changes manually (copy/paste or re-type) from pull requests just so I don't miss anything, but actually having the pull request is a good help thanks to GitHub's very clear diff tracking.

Share this post


Link to post
Share on other sites

I can see that the support for magic methods is now in PW source code. But my question is why do I only get $config to give the hints in Eclipse? The other variables like $page, $template, $user don't show the magic method given documentation. Can someone confirm that this works with PW and Eclipse? How to make it happen?

Share this post


Link to post
Share on other sites

Doesn't anybody use eclipse for PW development? I don't find a way to get the content assist in Eclipse to complete the variables like $page or $user. 

Share this post


Link to post
Share on other sites

You have to help PHPStorm to recognize ProcessWires API vars by including a PHPDoc section in your template file.

I created a gist for you which includes all (?) available API vars, simply paste this in your template file:

https://gist.github.com/phlppschrr/ea81285bdf56b497193b

To get even better autocompletion I can recommend the TemplateStubs module

  • Like 2

Share this post


Link to post
Share on other sites

I'm just testing the PHPStorm trial and it would be really nice to be able to use it's full potential. 

Share this post


Link to post
Share on other sites

As a sidenote though, simply defining the classes will not give the full picture, but a good part of it. Some methods that are added through hooks via modules like PagePermissions or LanguageSupport for the Page object won't be seen. I found this out lately while toying with Reflection classes trying to automate the Cheatsheet.

If anyone has any idea how to make this work, I'd be a taker. So far it doesn't seem possible unless the class explicitly adds the methods in its header docblock, and that itself has its own shortcomings.

Share this post


Link to post
Share on other sites

Not sure if this belongs here and maybe everybody knows it, but I just found out how to use code assistance of Netbeans IDE with Processwire code.

Looks helpful to me / for beginners.

/* @var $input ProcessWire\WireInput */

or in a class:

  /** @var ProcessWire\WireArray */
  protected $pw = NULL;

Hope it helps.

nbpwphpdoc.png

Share this post


Link to post
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


  • Recently Browsing   0 members

    No registered users viewing this page.

×
×
  • Create New...