4.9 DocBlockr

If you happen to work in a language or framework that really encourages commenting your code, the DocBlockr plugin is for you. We install it through Package Control. I will look for DocBlockr and there we go. Give it a few seconds and now we're ready to work with it. So let's create a file to work with. I will save this as, my-class.php. And within here, let's create a class. Class MyClass, like so. Now let's add a function, maybe we will call it run. For the arguments, maybe we'll accept the person who should be running and how far. Something like that will be fine. So now, we're just going to use pseudocode. We'll say, Return. Person needs to run how far miles. All right. That looks fine. So now watch what happens if before the method, I do forward slash and then two stars and hit Tab. With the DocBlocker plugin, this will immediately expand. And this is doing more than you think. It's not just giving you a snippet. It's also grabbing the params. So notice that it looked ahead and saw, hey, we're accepting a person and how far, so it populates two params. If I backtrack and we add an additional param, maybe direction or something like that. When I do it again, now it's going to give us three params. So then at this point, I can give the function a name. Instruct a person to run for a while. If I hit Tab again, its going to incrementally tab through each of those. So this first one will be a string, the description, we can leave that blank. The next one will be an integer, we'll leave that one blank and the final one is a string as well. Finally, what are we returning? We're going to return a string and now we're done. Now what's cool is that this DocBlockr plugin is fairly smart. So for example, if we add comments above the class, well, it's going to know, all right. We're not working with the method here, we're just describing the class. So let's take this just a little bit further to show you some of the other options that it provides. If I delete this entirely, watch what happens if I said a default value. So maybe the default person to run will be John Doe. Well, now if I run it, the plugin is going to detect that. Realize that its default value is a string and it will auto-populate the type for you for that specific parameter. Or if I backtrack just a ways, maybe we're going to make a handful of people run. Well, in that case, I'll set the name to people and then I'm going to typecast this in php, which says, we're expecting an array. And then to make this work, maybe we will do implode using a comma, the people's array and then we will concatenate on the rest. That looks fine and you know what? We're not really using direction here, so I'll get rid of that. So now that we've added type hinting, if I do it one more time, once again, the plugin is going to detect that and auto-populate the type for you. Now when it comes to the return value, the plugin will do a handful of things for you. So let me show you. Let's create another function, we'll say, isRunning and we will just return false or an empty string. It doesn't matter, really in this case. But the key is that we have the word is within the method name. So now when I run it, the plugin's going to detect that it has is in it and it knows that it's going to return a Boolean, likely. The same thing, I believe for has because typically, when you name methods in that way, a Boolean will be returned, so it knows to do that for you. Now this extends to a variety of things. So maybe if we have a function for setPerson, person. And then something like this, person equals person. Now when we run the plugin on that, it's going to realize that we are doing a set. We're using a setter method here, so nothing should be returned. And as you can see, it's not. So there's a couple other things that this plugin can do, but I leave it to you to figure that out for yourself. Let's move on to the next lesson now.