Add comments in the classes #153

Open
DavidePastore opened this Issue Mar 3, 2014 · 9 comments

6 participants

@DavidePastore

Do you believe it is possible to insert comments into classes so you know what each validator does?

@maxw3st

I have no idea what context this question is based on, but see no reason comments should not be possible, or even desired within classes.

@DavidePastore

If I use a IDE like Eclipse, I would like to see basic comments on every method to be sure to use the right one. Having opened the documentation and at the same time an IDE, it seems a little wasted.

My question is strongly rhetoric. 👘

@augustohp
Respect member

Do you believe it is possible to insert comments into classes so you know what each validator does?

It is, currently we have some comments aimed to IDEs on our rule builder class, maybe we are doing something bad there (or not compatible with your IDE) or you are using classes directly.

If you are using the builder (through v::yada()->yada()) and completion is not working then this is a bug.

If you are instantiating (rule) classes directly, then we really have another problem. The idea of not having doc blocks comments on every rule is to keep them simple (on maintenance) and following conventions. Maybe it was not the wisest decision we made, would love your input on that too, if possible.

@augustohp augustohp self-assigned this Mar 6, 2014
@DavidePastore

@augustohp I'm using Eclipse with PDT Plugin. Despite the plugin understands the variable class, it shows null at the description because it doesn't find the doc block comments.
validationwithouthelp
validationwithouthelp1

@augustohp augustohp added this to the 0.7.0 milestone Jun 26, 2014
@augustohp
Respect member

Hmn, I see! Since I don't use any IDE I don't know what actually needs to be done in order to the description of the rules to appear:

  1. If we add a description to every rule class, will Eclipse use it?
  2. If we need to add something else to the -gigantic- docblock on Validator class.

PS: Some feedback would be welcome if the change on #184 also works on Eclipse.

@augustohp augustohp removed their assignment Jun 26, 2014
@ghost

I use those DocBlocks (JavaDoc or PHPDoc) above each class, method and property as in the last method of the Validator class.
Looks like this and works great in Netbeans.

The advantage over one huge codeblock is that I can easily read those comments in file also, e.g. when I have to edit a method.
I heavily depend on it as I tend to forget what I have done 2 days ago.

@alganet
Respect member

I'm +1 for docblocks.

I've started adding them on Respect\Rest (sample) and even on its tests and it really helps.

For Validation though class docblocks won't help too much unless you use the concrete syntax, which looks like this:

use Respect\Validation\Rules as r;
$usernameValidator = new r\AllOf(
    new r\Alnum('_'),
    new r\Length(1, 15)
);

For the chain, we should probably also add short descriptions to the @method annotations on the Respect\Validation\Validator class.

@augustohp augustohp removed the Xtra Credit label Jul 28, 2014
@henriquemoody
Respect member

Actually it can be done in the megazord docblock on Validator class, like:

/**
 * @method static Validator allOf() Will validate if all inner validators validates

I don't use IDEs, can someone test it?

@henriquemoody henriquemoody modified the milestone: Backlog, 0.7.0 Jan 7, 2015
@henriquemoody henriquemoody modified the milestone: 2.0, Backlog Oct 7, 2015
@batusa
Respect member

PhpStorm:

validation autocomplete

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment