Do not deprecate @category #758

Open
tobiastom opened this Issue Feb 20, 2013 · 39 comments

6 participants

@tobiastom

I would like to encourage you to keep the @category tag and use it inside the default template.

I use the @package Project \ Sub-section already, but having at least a second categorization like @category Controller, @category Model or @category Import seems to be an excellent idea to group items by source.

With only the @package tag this would not be possible.

@boenrobot

I for one agree with you, and had already told @mvriel about this. Due to the recent large scale refactoring (#735), we've postponed discussions on that until that's over with.

Anyhow, @category can still remain deprecated IF @package is allowed to occur more than once, which was my suggestion. Personally, I'm OK with either scenario - keeping @category or letting @package occur more than once. I guess keeping @category (and extending it to occur more than once) will be better for BC, but re-purposing @package will be better in the long term, semantically speaking.

@tobiastom

Agreed. I also don't care which solution gets used, if at least one wins… :)

@package might be more intentional and not just another new keyword.

@mvriel
phpDocumentor member

@tobiastom your suggestion is remarkably similar to adding 'tags' to a structural element. Originally @category, @package and @subpackage together formed what now can be done with merely @package; because the new notation of @package obsoletes both @subpackage and @category.

Example:

/**
 * @category Model
 * @package phpDocumentor
 * @subpackage Parser
 */

is semantically equal to this new notation:

/**
 * @package Model\phpDocumentor\Parser
 */

Given the above I believe that @category does not add enough value given its current function and even adds confusion regarding its usage.

Regarding adding multiple @package tags, I am not so sure that multiple package really adds value.

@ashnazg can you take a look at the above and provide your opinion?

@ashnazg
phpDocumentor member

I'm not sure I understand what "multiple @package tags" would look like. This?

/**
 * @package Model
 * @package phpDocumentor
 * @package Parser

This would imply to me that the element belongs to these three, separate packages... thus "element-to-package" is no longer 1-to-1, but 1-to-many. I don't think this is what is being asked for.

Is our parser supposed to read multiple @package tags and put some significance on the order they appear in? Such that the above equates to:

/**
 * @category Model
 * @package phpDocumentor
 * @subpackage Parser

? I'm not sure that there is precedence for the parser to understand some relationship between the ordering of multiple occurrences of the same tag, so I doubt there is logic already there to accommodate such behavior. One might expect that @param is implemented this way, but I'm betting that @param behavior has always just been coincidental, in that you order your multiple @param tags to match your method signature out of habit... I do not think our parser is comparing the orders of both lists and acting in any way other than "show them just like they're listed".

If there remains widespread usage of @category in the field, even though not a single phpDoc 1.x output converter used it in any way in the resulting docs, then perhaps a very long deprecation period is in order. I agree with @mvriel that "@package Model\phpDocumentor\Parser" is the better migration option for non-namespaced code. Just like the old PEAR1 class naming standard (TopDir_SubDir_ClassName) was a pseudo-hack to act like true namespacing, @package was also a pseudo-hack to act like true namespacing.

@tobiastom

Sorry, just messed this up…

To add as an additional note: The package for files should be the same all the time. Category was just an idea to group files and classes into sections. Much as the mentioned tags above.

So the class Foo\Bam\SampleModel would be in

  • the @package Foo\Bam
  • the category Model

Inside the documentation I could then open the page for the "Model" category and see all models listed.

@tobiastom tobiastom closed this Apr 30, 2013
@tobiastom tobiastom reopened this Apr 30, 2013
@ashnazg
phpDocumentor member

@mvriel: do any of the 2.x output converters read the @category tag and use it to organize the resulting docs? None of the 1.x converters ever used it... this tag was only ever used when PEAR's own doc generator ran its own API docs using a custom converter.

@mvriel
phpDocumentor member

@ashnazg no, @category is currently ignored.

I think I understand what @tobiastom is getting at (being able to tag your code with a category, i.e. controller, model, service, etc) but I am not sure whether @category is the right tag for that. Perhaps another tag (@tag) would be far more descriptive?

@tobiastom

When reading the documentation it says: »The @category tag is used to organize groups of packages together.«. You are right that it's not suitable for my case. I would be ok with @tag – even if tag @tag has a strange reading for me.

@ashnazg
phpDocumentor member

Akin to a tag cloud, like you see on blog posts and photo groupings? In that use case, you would want to allow multiples, since this kind of usage means putting multiple grouping labels on a given thing.

For this to be useful, we'd want tag cloud behavior visible in the output docs, right?

@mvriel
phpDocumentor member

@ashnazg a tag cloud is one of the options, another would be to have an index with tags that people can use to get a list of controllers, or a list of models.

@tobiastom

I'm in favor of @mvriel idea with an index, but definitely added to the output docs.

Having multiple @tag items would be ok for me, but right now I don't think I would need that.

@ashnazg
phpDocumentor member

Actually, multiple @tag items would not be necessary... just require one @tag with a restricted syntax of "single-string tag values, whitespace-delimited".

@mvriel
phpDocumentor member

I think I would choose a comma (,) as separator as most tag-based solutions use that (suppose you'd want a space in it? i.e. Service provider) and allow one or more @tag tags. (I see no reason to limit it to one and that would offer the most flexibility to all coding styles)

@tobiastom

I think it depends on the implementation time. Having multiple tags would not be necessarily be a bad thing. Multiple means we can use it more then one time, but we do not have to. It it's not that much of a difference I would vote for multiple tags. Who knows what others might use this for. Model, Controller and Service are just the ones I came up with.

@boenrobot

This would imply to me that the element belongs to these three, separate packages... thus "element-to-package" is no longer 1-to-1, but 1-to-many. I don't think this is what is being asked for.

That's exactly what's being asked for... or, as mentioned, a kind of "tag". I think given that PhpDocumentor uses "tags" to document code blocks, having a "tag" called "tag" would be very confusing, which is why IMHO, repurposing @category or @package is a better course of action.

@mvriel
phpDocumentor member

Perhaps we should create a new improvement issue to brainstorm on and create an @tag tag? This should also be included in the new PSR

@mvriel
phpDocumentor member

I agree that @tag tag sounds a bit weird but repurposing @category sounds weird to me as well. I would definitely not use @package since that is not deprecated and has a clear other purpose (at least to me)

@boenrobot

Isn't this issue a fine place? :-P

What would be the point of @package if @tag appears? If I have exactly one @tag per class, am I not essentially doing the same thing?

@mvriel
phpDocumentor member

The name and description of the issue no longer match what is being discussed.

The point is meaning / semantics, packages are essentially namespaces for classes and files that do not use namespaces and provide a logical structure; whereas tags have no structure and may be documented in a separate location (index).

This is the same reason why multiple @package tags are not accurate as an element should not belong in two different locations in a hierarchy.

@boenrobot

have no structure and may be documented in a separate location (index).

But packages are already documented separately from namespaced elements.

element should not belong in two different locations in a hierarchy.

Isn't the whole point of PHP namespaces to provide such a hierarchy? Why keep a duplicate of this functionality? And even with it being kept for whatever reason... why not use @category then? "Tags" are sometimes being described exactly as "a category" to the uninitiated, so simply saying "category can occur multiple times, and the structural element will be considered to be part of all of them" will make it crystal clear.

@ashnazg
phpDocumentor member

I reckon I could live with @category remaining and taking on this new "tag cloud" use case. My original point for deprecation was because I saw no usage of it in output docs' behavior, and therefore expected no real usage in the wild.

@tobiastom

What does other documentation tools say about @category? Is that used in doxygen or other systems?

If they do not advertise a different use case, I would prefer to use (multiple) @category tags.

@mvriel
phpDocumentor member

have no structure and may be documented in a separate location (index).

But packages are already documented separately from namespaced elements.

But packages are a substitution for namespacing in projects that do not use namespaces, they have always represented a hierarchy, a fixed structure. In my opinion, breaking from that semantic meaning does not add clarity but adds confusion to the function of the tag.

element should not belong in two different locations in a hierarchy.

Isn't the whole point of PHP namespaces to provide such a hierarchy? Why keep a duplicate of this functionality?

As described above, because

  1. only a small amount of projects use namespaces and those that don't rely on packages
  2. a large amount of existing projects use the package tag

And even with it being kept for whatever reason... why not use @category then? "Tags" are sometimes being described exactly as "a category" to the uninitiated, so simply saying "category can occur multiple times, and the structural element will be considered to be part of all of them" will make it crystal clear.

This might be me feeling uncomfortable but changing the semantic meaning of a tag this late is problematic as some people are bound to use it and do not feel comfortable with changing their code base.

For example, Magento uses the category tag in all their files as a top level 'vendor' (example: https://github.com/magento/magento2/blob/master/app/Mage.php) as do PEAR projects (https://github.com/pear/Net_IPv6/blob/trunk/Net/IPv6.php), or projects using the PEAR coding standards (http://pear.php.net/manual/en/standards.sample.php).

So: repurposing the category tag 'removes' the top-level package name for a substantial number of projects and instead adds a single tag (perhaps multiple in large projects?).

If we do this, we should not take this lightly and accept that phpDocumentor 2 is no longer compatible with phpDocumentor 1 (despite all changes in phpDocumentor 2; its goal has and will be complete compatiblity).

I do not see the benefit of re-using the category tag versus these possible issues when we can avoid them by reintroducing a tag with a different name. Perhaps another language has already implemented this with a different name that we can re-use?

@boenrobot

@mvriel
If you look closely at how all of these projects use @category, you'll notice that the package name includes the "category" name.

In other words - there's no inherit added value of having exactly one @category, since the @package tag includes it. That's kind'a why the tag was supposed to be deprecated - because it duplicated what was already part of @package without adding value to it.

If @category is allowed to occur multiple times, all those projects are still going to get exactly what they're expecting - a category list that happens to include all packages under the category they've specified.

The added value will appear to those that have more than one category, in that they'd be able to find the structural element under more than one category (or better yet - be able to see elements that occur in more than one category at a time, similarly to picture tags at programs like Picasa or Windows Live Gallery).

There's no "break" in anything with this.

@tobiastom

What does other documentation tools say about @category? Is that used in doxygen or other systems?

If they do not advertise a different use case, I would prefer to use (multiple) @category tags.

As far as Doxygen is concerned, it currently ignores @category for anything other than Objective-C:
http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdcategory

AFAIK, other tools, if they're aware of @category at all, do exactly what one would expect - generate a list of categories, with each typically including packages that happen to have the same prefix as the category name.

@tobiastom

@boenrobot Thanks for the info. So doxgen uses it for something completely different.

So I would recommend to use @category for this tag-like structure.

@mvriel
phpDocumentor member

Given priorities I am unable to finish this discussion and add an implementation for version 2.0. For now I guess the most sane thing I can do is make @category not deprecated until further notice and maintain status quo (which is, show it in the class view but take no specific action on it).

@tobiastom

Maybe you could give us some hints on how to implement it like we discussed here (a simple list view), and maybe one might contribute a pull request.

Still, glad that we can agree on not deprecate @category. 👍

@boenrobot
  • The project descriptor needs to end up containing an index of elements belonging to a certain category, analogous to that for packages. I haven't yet digged enough into the post-refactored code to tell you how that would happen, or else I'd probably do it myself.
  • The template's template.xml file needs to be adjusted to generate new files based on that index, ideally with a new more appropriate UI (worse case scenario: reuse the one for packages).
@mvriel
phpDocumentor member

I'd prefer it if no work is done on this item; I do not want to repurpose @category for this purpose and further discussion is necessary to have a tag cloud / tags index functionality

@boenrobot

Any particular person/team you'd like to hear the opinion of?

@mage2-team, @CloCkWeRX, @saltybeagle? (I hope GitHub's "mention" functionality works even for edits...)

@mvriel
phpDocumentor member

@boenrobot at the moment I'd like to suspend the discussion to be honest; I am focussing all my efforts on the stable release and this is not a light topic as far as I am concerned

@boenrobot

At least assign it as a "do for 2.1 milestone" then?

@magento-team

Any particular person/team you'd like to hear the opinion of?
@mage2-team, @CloCkWeRX, @saltybeagle? (I hope GitHub's "mention" functionality works even for edits...)

Yes, it works. Thank you for notifying.

Currently, in the internal coding standard for Magento 2.x, we deny using @category for the following reasons:

  1. It has no significant effect on API documentation and is not recommended by PHPDocumentor: http://www.phpdoc.org/docs/latest/for-users/tags/category.html

  2. Right now the PHPDocumentor guide indicates:

    If, across the board, both logical and functional subdivisions are equal is it NOT RECOMMENDED to use the @package tag, to prevent maintenance overhead.

It seems like in most of legacy Magento source code the distinction of @category VS @package is not clear and it happens to repeat modules' namespace in the @category across the board. So there is little value in it.

@boenrobot

@mage2-team
Thank you for responding.

So are you saying that if we repurpose @category to act as a "tag cloud marker" of sorts (akin to picture galleries' "tags"), this would not cause any (noticeable/significant?) disruption to your API docs, and would in fact encourage you to start adding it back in newer code (due to the then added value)? Would such a functionality be a useful extra for the Magento project?

@magento-team

@boenrobot

to act as a "tag cloud marker" of sorts (akin to picture galleries' "tags")

It might bring some value. For example, merely to organize into categories components of the system.

Although it is worth mentioning that in Magento 2.x we are reshuffling source code and introducing "convention over configuration" in some places, so necessity of "tagging" does not emerge in the first place. To illustrate this, take a look at Magento 1.x code, the Mage_Catalog module:

  • app/code/core/Mage/Catalog/*.php -- the most of the module's source code. Models, controllers, helpers, blocks
  • app/design/frontend/base/default/template/catalog/product/view.phtml -- a template for Mage_Catalog_Block_Product_View. Essentially, this template is an indefeasible part of the block. But the files are in completely different directories and one may want to "tag" them with "Mage_Catalog" identifier, so that reader who reviews API docs, would see all files related to Mage_Catalog module
  • app/design/frontend/default/modern/template/catalog/product/view.phtml -- that would be a template file overridden in default/modern theme

Now in Magento 2.x, the base template would reside in the module directory:

  • app/code/Mage/Catalog/view/frontend/product/view.phtml -- you don't really need to mark this file with any tag, because it already resides in the module
  • app/design/frontend/default/modern/Mage_Catalog/product/view.phtml -- here the fully qualified module name is already part of template file path conventionally
@mvriel
phpDocumentor member

So are you saying that if we repurpose @category to

I hate to sound negative here yet as long as I do not see a strong argument why to repurpose @category instead of adding a new tag that describes the 'tag' semantics I am a firm opponent of repurposing for reasons explained earlier in this thread.

This does not mean that I am an opponent of the tagging functionality, far from it; I am a proponent of that.

@tobiastom
@boenrobot

I am a firm opponent of repurposing for reasons explained earlier in this thread.

Right. Your reason is basically "it's a breaking change".... and I say "it's not", as evidenced by the fact that people either add a single copy without expecting anything to happen anywhere (which is what PEAR and PEAR2 do; and that was the original reason for deprecating the tag), or (as Magento does with newer code) remove it altogether.

The only thing that would potentially need modification is for the PEAR CS to allow this tag to occur more than once, but that's not a "backdraw incompatibility" issue then, but an "enhancement" issue, since the existing doc blocks of existing PEAR(2) packages will be processed fine with or without such modifications.

I could see your earlier argument about enhancing @package being problematic, in that other DGAs might have issues with that due to their special treatment of it. But with @category that's not the case - all DGAs (that I know of) ignore it (or should I say, "treat it as an unrecognized tag"), and only coding style tools take any notice of it.

Besides,

The discussion is about @category because I thought this tagging like feature was the initial intention.

in all honesty, I first thought that too, because I had long noticed that the package name included the category name... which would be pointless unless a tag-like functionality was the intention.

@mvriel mvriel removed the Waiting label Dec 2, 2015
@jcrben

@category isn't as semantically clear as @tag to me, as in my mind a thing generally only has one category. Tagging is a common and well-understood feature, so @tag makes sense. Agree with @mvriel

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