Properly use @see

Then I guess this should be added to Coder's review rules...

I'd like to add this to coder's comment review. I spent 10 minutes trying to write the rule for this, but since drumm is being very specific here, there appear to actually be several rules. If one of you wants to write the regex, I'd be happy to make sure that the coder rules syntax is correct. What coder needs, is the regex of non-conforming code. See http://drupal.org/node/144172 for help on writing rules.

Hi,

I've added in @see usage rules/checks to the 5.x and 6.x versions of the coder module. It ensures that the following conditions are met:

• @see should always be at the beginning of a line, never inline in other comments.
• Always follow function names with ().
• Separate multiple references with ', '
• No trailing punctuation, this is not a sentence.

Please download the dev version and test it.

The only condition not checked is "Keep the references on the same line.". If someone wants to provide me a rule that does this, I'd be happy to try it out. See http://drupal.org/node/144172 for help on writing rules.

Cheers,
Stella

Stella, did you forget to attach the patch?

You can try the attached patch or the latest 5.x-2.x-dev version.

Cheers,
Stella

Attachment	Size
coder_178629.patch	2.41 KB

Coder is now identifying quite a few @see problems, many of which may be false positives. I think that @see template.tpl.php is valid.

If that is the case, then requirements above are incorrect. Drumm - can you clarify the requirements for us?

Cheers,
Stella

All valid:

All invalid:

Dunno, whether @see in single-line comments are actually parsed, but they are perfectly valid, too, so the same rules should apply.

Please try out the attached patch. The previous one has already been checked into CVS, so this one has an additional check for:

It will just accept filenames that end in .php or .inc, so as to distinguish it from a normal string or a function name without a trailing (). If this is incorrect, please let me know.

Cheers,
Stella

Attachment	Size
coder_5x_178629.patch	1.69 KB
coder_6x_178629.patch	1.69 KB

Thanks heaps!
I like @see

I generally use it to (at least) refer back to the hook_***() definition when implimenting, or to the parent routine when making a trivial helper func.
Sometimes to link related form API funcs - (formname, formname_validate, formname_submit, formname_theme)
Often when I steal code from core to over-ride in my themes (over-ride of @see theme_menu_item() )

Any other suggestions folk think is good practice?

@stella: A developer may reference to any file, including:

In general, function names cannot contain dots, but filenames usually have at least one.

Ok, thanks for the clarification. The attached patch assumes that if it doesn't have a . then it's a filename, otherwise it's a function and must be followed by ().

However I've just thought of another case. Is the following a valid scenario (ignore spacing)?

Cheers,
Stella

Attachment	Size
coder_6x_178629.patch	1.68 KB

Yes, multiple references on one line are valid, and, listing a file in front of a function is valid, too.

Thoughts:
- There should be exactly one space behind @see (so \s* should simply be )
- Since multiple values are allowed, we might need a look-behind to force matching of a dot for filenames, because the dot in [a-zA-Z_\.] is optional and thus, would also match a function name.

I think the first condition [a-zA-Z_]+\(\) matches a valid function name.

Try the attached patch. I made a couple of changes.

• Numeric characters weren't being matched in filenames or function names and should be valid.
• Previous patches only alerted on invalid function/file names for the first reference on a line.
• It can now handle mixed function and filename references and tests for a ", " separator.
• It ensures that there is only one space between the @see and the first reference.

I'd appreciate if you could test the patch again.

Cheers,
Stella

Attachment	Size
coder_178629.patch	3.55 KB

Sorry, no review this time. Just wanted to leave a quick note that URLs should be valid for @see, too. A common practice for referencing to d.o issues, PHP bugs, and other pages is

Ok will look at adding support for this.

Ok try the attached patch, hopefully this one will catch all scenarios!

Cheers,
Stella

Attachment	Size
coder_178629.patch	3.58 KB

In the suggested patch, function names like "foo.bar()" are accepted, which seems incorrect. The "." is accepted for file names, but not for functions.