0

I'm developing a WP theme and I'm commenting my PHP code using PHPDoc. I would like to add versions of large code blocks, so the customer knows when it's updated.

Let's say I release initial version 1.0.0, then I update some code in version 1.0.2. How do I document that the code is changed? Will this be correct:

/**
 * Code block #1
 * 
 * @since ThemeVersion 1.0.0
 * @version 1.0.2
 */

I'm not sure this is a correct way to use @version, since on the other hand I have another case when another block of code have not been changed after the update:

/**
 * Code block #2
 * 
 * @since ThemeVersion 1.0.2
 * @version 1.0.0
 */

So not sure if this makes sense.. please let me know your thoughts.

Thank you.

Spiridon
  • 13
  • 3
  • meanwhile it seems to be possible. Have a look: https://github.com/phpDocumentor/ReflectionDocBlock/blob/master/examples/04-adding-your-own-tag.php – summsel May 09 '19 at 09:06

1 Answers1

0

Your use case is a reasonable use of the combination of both tags.

As such, I would expect your usage in Code Block #1 to mean:

  • this block was created in Theme v1.0.0
  • this block was last modified by Theme v1.0.2

(note that the current Theme version in use by the consumer could be v2.0.0, but these tag values still mean what they mean -- even if this installed Theme is v2.0.0, this code block #1 was added originally in v1.0.0, and was last changed in v1.0.2)

Now, on your Code Block #2:

  • @since ThemeVersion 1.0.2 should be telling me that the block was first created in Theme v.1.0.2
  • but @version 1.0.0 tells me it was last modified by v1.0.0... but that can't be right, because it wasn't even in the code until v1.0.2.

(if you set both tag values to 1.0.0, that would say to me "block #2 was created in v1.0.0 and has not been changed yet).

ashnazg
  • 6,558
  • 2
  • 32
  • 39