According to PHPDocumentor's documentation, to show an example it would be like this:
#example [location] [<start-line> [<number-of-lines>] ] [<description>]
This seems like a valid solution if code never changes but whenever you go and add new code to wherever the location is, your start-line potentially changes meaning you have to constantly be updating these various references.
Is there a better way to show an example of how to use a class method, within the DocBlock, without referencing an external current use example?
Here is what I am aiming for:
/**
* #example This is how you use this method:
*
* $baz = Foo::bar( array('bing' => $bing) );
*/
And then it shows up in the documentation as an example. Any ideas?
You can show a code example in the docblock itself by means of the "code" delimiter. So, for your original example:
/**
* This is how you use this method:
* <code>
* $baz = Foo::bar( array('bing' => $bing) );
* </code>
*/
The manual page [1] for the #example tag shows both a "code" section in the docblock as well as #example pointers to lines in separate files.
[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.example.pkg.html
Related
Disclaimer: Unless I'm not seeing, this is not the same as described in this topic and I'll need some time to fully explain the situation.
A very long time ago I asked a question about how to use the REGEXP operator in a SQLite statement. The operator is not implemented by default but it can be in runtime.
Well.. As you can see by the dates, that worked for me for years. Not entirely with the help of that topic (someone in SQLite mailing list showed me a trick) but it worked well.
Because preg_match() works differently of ereg() (as I've heard), by returning positively immediately after the first match, I took an additional precaution before populate that SQLite database by sorting the REGEXES (I'm sure this is not the right plural form) from the longest (more specific) to the shortest (more generic).
Not a big deal, just a simple uasort() using strlen().
Considering a fictional movie management catalog with two URLs like management/actors and management/actors/add, this sorting trick saved me from having false-positives while accessing the first URL and have SQLite responding with the second resultset only because both of them have the same immutable part management/actors
This is the current implementation:
$this -> dbh
-> sqliteCreateFunction(
'REGEXP',
function( $r, $s ) {
return ( preg_match( sprintf( '#^%s$#i', $r ), $s ) != 0 );
},
2
);
Being $this -> dbh the class property with the PDO instance used.
The situation now is different because this sorting trick did not consider one possibility: Two routes where the most generic is also the longest route. For example: management/actors/add and management/actors/overview.
Conceptually, the second route is more generic because it refers to a simple dashboard listing all the actors and should go to the bottom. In fact it's just an alias for management/actors.
And the second route is more specific because it routes the form responsible to add a new record and thus should go to the top
These routes are analyzed from PHP doc comments spread around Controller classes like this:
/**
* Overview
*
* !Route GET, management/actors
* !Route GET, management/actors/overview
*/
final public function overview() {}
/**
* Add
*
* !Route GET, management/actors/add
*/
final public function add() {}
And comes in this order:
management/actors
management/actors/overview
management/actors/add
Because I need to identify the Action method they're structurd in different array indexes with the class method name as key:
Array(
'overview' => array(
[0] => management/actors
[1] => management/actors/overview
),
'add' => array(
[0] => 'management/actors/add'
)
)
Like I said the sorting works and can make this structure become:
Array(
'overview' => array(
[0] => management/actors/overview
[1] => management/actors
),
'add' => array(
[0] => 'management/actors/add'
)
)
But the whole component fails to work because of preg_match() implementation of SQLite REGEX operator.
So far, the only way, I managed to workaround this issue was to develop the Controller classes like this:
/**
* Add
*
* !Route GET, management/projects/add
*/
final public function add() {}
/**
* Overview
*
* !Route GET, management/projects
* !Route GET, management/projects/overview
*/
final public function overview() {}
I mean, in the reverse order.
Fine! All applications in a certain way have their own oddities and I could live with that but, perhaps, in the future, someone else may open this code and give it some maintenance and may not be aware of this limitation.
That said (finally) I wish to know if there is a way to increase preg_match()'s gluttony and make it not stop in the first positive occurrence and match the longest possible like ereg does, or at least I think it does, I've never saw it in action.
Or an alternative solution, of course :p
As requested in comments, some examples of the REGEXES, listed in the order they're inserted in the SQLite database (after sorting):
management/projects/overview\b(.*?)
management/projects/add\b(.*?)
management/projects\b(.*?)
They're very simple REGEXES. They match mainly the Request URI. In the end of the REGEX I have only a border to distinguish the fixed string text from the variable part that might exists (like Xdebug profiling GET argument)
I am using request object in twig extension class to get the current route. For instance, having the following url:
http://www.localhost/project/user/page/2
Inside of the twig extension I'm able to get user/page/2 string and do something with it.
The problem arises when I wanna get the default route using the same method, which I have to do. For example, accessing the following url:
http://www.localhost/project/user
I want to get user/page/1 string inside the twig extension class, and not just user.
The controller looks like this:
/**
* #Route(name="user",
* default="user/page/1")
*/
Is there a way to achieve that? Or do I have to stop using default routes?
Write a comment if you need more explanation, it's 9AM here in Poland and I'm sleeping yet.
The #Route documentation explains that you can do this for set a default page number:
/**
* #Route("/project/user/page/{page}",
* name="user",
* defaults={"page" = 1},
* requirements={"page" = "\d+"}
* )
*/
After I create a method I use /**<enter> to generate the DocBlock. It auto fills the #param and #return for that function.
Example:
/**
*
* #param type $str
* #return type
*/
public function strlen($str){
return strlen($str);
}
How can I customize the block being generated so that it also fills in the #author and end up with this after /**<enter>
/**
*
* #param type $str
* #return type
* #author John Doe <john#doe.com>
*/
public function strlen($str){
return strlen($str);
}
Thanks
There may be a better way to do this, but here's what I've used: under Tools > Options > Editor > Code Templates, there are some predefined combos for generating code quickly. One of the default templates in 7.0 is:
vdoc<tab>
This generates a pseudo-docblock and the variable definition. You can replace this and add new ones that expand into whatever text you want, much like vim abbreviations. You can find more on this on the Netbeans documentation site:
http://netbeans.org/kb/docs/php/code-templates.html#using-templates
I believe the answer you're looking for will be found here: phpDocumentor Tutorial
I think you'll want to look at the --customtags Command-line switch.
So most likely, when you go to Tools -> Options -> "PHP" -> "PHPDoc", you can add that --customtags command-line switch into the PHPDoc script line.
I haven't attempted this personally, but I have been playing around with the idea of using NetBeans in combination with DocBlocks and PHPDocumentor to "automagically" create a good amount of usable documentation without being too strenuous on the rest of the coders. ;-)
There's a nice video tutorial about setting up NetBeans to work with PHPDocumentor available here: Generating PHP Documentation With NetBeans IDE 7.0
To enable proper #author tag autocompletion, just go to: Tools->Templates->PHP->PHP Class, press the "Settings" button and uncomment the line starting with #user=.
Now you're able to edit the name and email, which are passed to your Class comment.
Short Answer from various sources: No you can't edit a template that could add it for you.
If you are still looking for a feature alike, you can create a Macro do to it and then bind it to a shortcut ("Alt + W" for instance).
To create a Macro : Tools -> Options -> Editor -> Macros
Example :
Alt+W => insert-break "/**" insert-break
This Macro helps add PHPDoc with the left hand which makes it faster. You can generate whatever you wish to generate like using this Macro, and then placing the cursor at the right place and then adding the #author YOUR_NAME at the end of the comment.
You can also set the general Author of your project by going to : Tools -> Templates; Click "Settings"
Add the line :
user=YOUR NAME <email.prefix at domain.extension>
This will add the #author to all your new class/interface definitions.
I hope this will help you!
I very much enjoy working in Notepad++, but I haven't yet found a plugin to automatically do PHPDoc style comments. Other PHP IDE's (Eclipse, NetBeans, ZendStudio) include this feature, and it's quite handy.
Basically what I want is, if on the line above a function definition or class definition I type in:
/**
It automatically populates the PHPdoc format (something like the following for a function):
/**
*
* #param $first_argument
* #param $second_argument
* #return
*/
Then when I type in additional lines to the comment, it starts each line with an asterisk.
Is there a NP++ plugin that accomplishes this, or a way to tweak NP++ to make it work?
The question is old...but try DoxyIt plugin from plug manager. It works exactly as you need.
While Notepad++'s syntax highlighter recognizes doc comments, it does not actually parse them and generate the corresponding autocomplete code for you, nor does it have any snippet features that allow you to insert doc comments on the fly.
Try DocIt, it works fine, after install move cursor before function and press CTRL + ALT + SHIFT + D to add comments.
Download: https://sourceforge.net/projects/nppdocit/postdownload
I think there aren't a "really tool" por PHPDoc on N++. You can use the WebEdit plugin (plugin manager). Once installed you need to update the edit file adding this line at the end:
pdoc=/**\n * \n * \n * #params \n * #return \n */
Restart N++, write pdoc and press Alt+Enter to get anything like this:
/**
*
*
* #params
* #return
*/
Obviously, it can't get your function params and other tipical info of DocBloks but may be helpfull if we have no choice.
I guess the selected answer is older than the plugin itself but I use DocIt. http://nppdocit.sourceforge.net/
Passing uid as an argument works fine with this code:
$bouts = views_get_view_result('Results', 'page_1', array($user->uid));
The key line in views_get_view_result that sets arguments is:
$view->set_arguments($args);
But what about passing date ranges?
Also, if something is specified as a filter on a view, is there a way to prorammatically alter it?
views_get_view_result:
/**
* Investigate the result of a view.
* from Drupal.org.
*
* #param string $viewname
* The name of the view to retrieve the data from.
* #param string $display_id
* The display id. On the edit page for the view in question, you'll find
* a list of displays at the left side of the control area. "Defaults"
* will be at the top of that list. Hover your cursor over the name of the
* display you want to use. A URL will appear in the status bar of your
* browser. This is usually at the bottom of the window, in the chrome.
* Everything after #views-tab- is the display ID, e.g. page_1.
* #param array $args
* Array of arguments. (no keys, just args)
* #return
* array
* An array containing an object for each view item.
* string
* If the view is not found a message is returned.
*/
function views_get_view_result($viewname, $display_id = NULL, $args = NULL) {
$view = views_get_view($viewname);
if (is_object($view)) {
if (is_array($args)) {
$view->set_arguments($args);
}
if (is_string($display_id)) {
$view->set_display($display_id);
}
else {
$view->init_display();
}
$view->pre_execute();
$view->execute();
/* print "<pre> $viewname: $display_id";
print_r(get_class_methods($view)); */
return $view->result;
}
else {
return t('View %viewname not found.', array('%viewname' => $viewname));
}
}
As for passing data ranges and given the posted function definition, you could pass date ranges to that only if the view would accept them as arguments. I'm not 100% sure, but afaik date ranges can only be defined as filters, not as arguments, which leads to your second Question:
Programmatically altering the views filter settings is possible, but a bit messy, given the rather complicated view object/array mashup structure. In your posted function above, the first line is
$view = views_get_view($viewname);
After that, $view contains the whole view object. The filter settings are defined per display, so assuming you have a view with only a default display, you will find the filter settings under
$view->display['default']->display_options['filters']
(Note the object/array notation mix - the display is a contained object of type views_display)
The 'filters' array contains one entry per filter, with varying elements depending on the filter type. For your purpose, I would suggest to create a dummy view with just the filter you are interested in, with preconfigured/hardcoded values. Using a debugger (or var_dump/print_r) you can then take a look at the filter array after view creation. From what you find there, you should be able to deduce how to inject your custom date range.
Disclaimer: Poking around in the view like this is a bit annoying and not to effective, but it works. As of yet, I have not found a concise documentation of Views2 that would explain the innards in a straight forward way, as I find the official API documentation a bit lacking concerning the usage from code. (Of course this could well be just me being to stupid ;)
If you're using views 2, you can use the GUI to add a date argument. Then in the url, you can put :
www.yousite.com/yourview/startDate--finishDate
For the startDate/finishDate, the format is YYYY-MM-DD-HH.
GL!