[policy, no patch] Decide on documentation standards for namespaced items

The API module does not support linking with namespaces in it. Are people changing the @see to include namespaces already? If so:
a) standards on http://drupal.org/node/1354 need to be updated to say classes should always have namespaces
b) API module needs to support them. BUT this is a big undertaking, especially since Grammar Parser doesn't currently support namespaces...

We need to make a decision on this, whether in API docs, we should be doing:

* @see Drupal\Core\Database\Query\Condition::compile()

or

* @see \Drupal\Core\Database\Query\Condition::compile()

(i.e., whether the namespaces in docs should start with \ or not.

Im not able to add much to this discussion, but in PHPStorm, at least, a @return won't correctly return the right class through the IDE if it's not preceded by a \.

What I would like to see is consistency -- so we should either always (in documentation) use the \ or never use the \.

Argument for requiring the backslash:
- At least some IDEs require it to understand param/return types.

Argument against:
- In actual PHP syntax, use/namespace declaration lines do *not* include a leading backslash (I think?). So requiring it in documentation seems... weird.

As far as vendor code goes... Symfony even using its own full namespaces in a @tag line seems to be rare. In the 15 instances where an @return includes the string 'Symfony', 7 start with a backslash and 8 don't. For @param, there are 2 that have the string 'Symfony' and neither has the backslash. In @var, 19 'Symfony', of which 15 start with backslash. In @see, there are 4 'Symfony' and none has the backslash. This doesn't feel compelling to me one way or the other.

So... The questions I would like us to answer?

a) If we are doing documentation and there is an @namespace at the top of the file or one or more @use declarations, so that in PHP code we would not need to use the fully namespaced class, should we even require (or encourage) documentation to have the fully namespaced class in it, or should we encourage dropping the namespace? Or should we require/encourage it only if it's outside the namespace declaration (i.e., if it's in a "use" namespace but not in the main "namespace" declaration)?

b) Where we do require/encourage the namespace to be provided, should we require it to start with \?

I am a bit agnostic on both answers. If the answer to (a) is that we don't generally put namespaces in documentation, it will complicate the API module code somewhat, but not all that much really. And it would make for easier and cleaner documentation to omit the namespaces entirely (which I think is consistent with most of Symfony by the way). And it would make the documentation behave like the code (we would only put namespaces in where the code would require it.

On (b), my aesthetic sense again says that documentation should be like PHP code (no backslash), but if IDEs are requiring the backslash (why??? I don't get that...), then we might want to go with that.

Thoughts?

First off, we should look at multiple common IDEs and see what they do; beta versions of them if available, so that we can be forward looking. (And, potentially, file bugs upstream with the IDEs if they're doing something we consider stupid.)

That's the only external dependency, really; everything else is internal and/or aesthetic as long as we have our own API doc parser.

My knee-jerk response is to not have a leading \ to parallel PHP code (we went with no leading slash there because PHP's own functions return full class names without a leading \), but we should still look into the above considerations.

(Note: I'm not a namespace expert...)

I just noticed one PHP namespace syntax oddity: Although in use/namespace lines, they are assumed to be global (so by convention you do not start with a backslash), when doing

$foo = new \fully\namespaced\className();

you do. If you leave off the initial backslash, it's assumed to be a sub-namespace of your current namespace.

So there is some support in PHP code for the idea of starting with a backslash.

PHP namespaces are very oddity. :-)

Actually the class will fallback, too. So this should (I think) work:

namespace Foo\Bar;

class Baz;

namespace Narf;

$b = new Foo\Bar\Baz();

I've looked into this further...

As described in http://www.php.net/manual/en/language.namespaces.basics.php, the use of a slash at the beginning of a namespace denotes a Fully Qualified namespace (absolute), while no slash is merely a Qualified (relative) namespace. This works exactly like a file system, and you one means a different thing from the other. There is no need for us to have a policy on this, as its just how PHP works.

So the question is not, "Do we use a slash", but, "Do we expect fully qualified classes in documentation or not"?

It seems relatively straightforward to me... Documentation is not covered by namespaces (obviously) and, while it may be feasible to rely on documentation parsers to work out qualified class names based on their current namespace scope (though I'm not sure that even happens), it seems smarter to simply require a fully qualified class name (which includes the backslash). That removes ambiguity and is much clearer. This goes doubly for files which use multiple namespaces (though thats generally not recommended).

@crell, in your example given in #9, you'll get a fatal error for an undefined class Foo\Bar\Baz(), as classes must have fully qualifed name (functions will fallback, however). I've worked up an example which shows class and function namespace fallback behaviour. This also demonstrates the usefulness of using the fully qualified name in documentation, to make the code clearer.

EDIT: Drupal striped my slashes, so Ive replaced them with pipes so you can read it. If you want to try this in your own editor, globally replace the pipes.

/**
 * Global namespace
 */
namespace {
  class Baz {
    function __construct(){
      return TRUE;
    }
  };

  function Foz() {
    return TRUE;
  }

}

/**
 * |Foo|Bar namespace
 */
namespace Foo|Bar {
  class Baz {
    function __construct(){
      return TRUE;
    }
  };

  function Foz() {
    return TRUE;
  }

}

/**
 * |Narf|Foo|Bar namespace
 */
namespace Narf|Foo|Bar {
  class Baz {
    function __construct(){
      return TRUE;
    }
  };

}

/**
 * |Narf namespace
 */
namespace Narf {

  // Calls |Narf|Foo|Bar|Baz(), not |Foo|Bar|Baz()
  $b = new Foo|Bar|Baz();

  // Fatal error
  // Class Baz() does not exist in |Narf
  $b = new Baz();

  // Calls |Baz()
  $b = new |Baz();

  // Calls |Foo|Bar|Baz()
  $b = new |Foo|Bar|Baz();

  // Calls |Foo|Bar|Foz()
  // Functions will cascade down
  $b = Foo|Bar|Foz();

  // Calls |Foz
  // Functions will cascade down
  $b = Foz();
}

OK, I'm convinced by the arguments.

PROPOSED STANDARD:

--------
All references to namespaced classes in documentation blocks should include the fully-qualified namespace (starting with a backslash). This applies whether the class is mentioned in documentation text, or an @see line, or wherever else it might appear; it applies whether the class mentioned is in the namespace of the current file or in another namespace (in other words: there are no exceptions to this rule). Examples:

GOOD:
 * something about the \Drupal\Core\Database\Query\Condition::compile() method.
 * @see \Drupal\Core\Database\Query\Condition
BAD:
 * something about the Condition::compile() method.
 * @see Drupal\Core\Database\Query\Condition::compile()

----------

Any votes yes or no, given all of the above?

I hate PHP...

I can agree for @see, @return, etc. For descriptions, given how long the class names can get I'd like to be able to short-circuit it and just use the short name, for readability. Those rarely link anyway, don't they? Plus presumably they can still be mentioned in a @see anyway if you want a link.

I'm thinking of, say, DB documentation that says "uses the same algorithm as the Condition class" or something like that, which then has a class name that runs close to the 80-character limit all on its own. That's very bad for readability.

RE #13: "Those rarely link anyway" -- on the contrary, class names (and members too) in documentation text *always* link if the API module can figure out what to link them to.

For myself (and for the API module), I think it would be fine if our policy was that class names only need namespaces if they are outside of the declared namespace for the file. However, as has been pointed out above, in certain places (@param/@return types) for IDE compatibility, we apparently need the fully-qualified namespace. So rather than making a complicated policy that says "Sometimes use the namespace and sometimes doesn't, and by the way you can sometimes start with a backslash and sometimes not", I think it is actually better (at the expense of a bit of extra typing) just to say "Use the fully-qualified namespace, period.".

I agree for @ declarations. It's for the descriptive body or godforbid the short-desc that I think using the full class name would make it unreadable for humans. If we want a short-name in the description and then a link, then you can use @see.

/**
  * Do something cool with a Thingie object.
  *
  * The Thingie must be pre-configured with a dodad.
  * 
  * @param \Drupal\mymodule\Plugins\Thingies\Thingie $thingie
  *   The thingie that shall be made cool.
  * 
  */
function be_cool(Thingie $thingie) { ... } 

Hm. I'm not excited by the proposal in #15. The API module will not have better or worse luck making links in plain documentation links vs. within an @tag area, and human readers/writers of documentation will not find it any less tedious (or on the other hand, less specific/clear) to have namespaces in one place or the other.

Only IDEs care, I think, and I think only about the return type and maybe the @param type. So if we're going to make a specification that minimizes the tedium, I think we should say:

---
When mentioning class names in documentation headers, if the class is within the current file's namespace, omit the namespace (just use the class name). The only exception is when providing a class/interface as the @param/@return type, in which case you should always include the fully-qualified namespace (starting with a backslash). For classes outside the current file's namespace, always include the fully-qualified namespace.

For example, if we have classes \Space\One\Foo, \Space\One\FooStuff, and \Space\Two\Bar, and we're documenting Foo::baz():

/**
 * Does something really cool.
 *
 * Here we talk about some other method FooStuff::whatever(), and about
 * Foo::something().
 *
 * @param \Space\One\FooStuff $stuff
 *   Description including something about the FooStuff class.
 *
 * @return \Space\TwoBar
 *   Description including something about the \Space\Two\Bar class.
 */
function baz(FooStuff $stuff) {}

If you mention Two\Bar in the description of @return \Space\Two\Bar, isn't it sufficiently obvious which you mean? That could still cause all sorts of alignment issues and be difficult to read. Otherwise I'd be OK with #16.

#17: I think thats what was intended in #16.

I'd like to propose a different wording to #16 which

• favours fully qualified in the wording by default, rather than the other way around, as I think some folks might struggle with this one (after all, we are), and we don't want to create confusion around relative/absolute namespaces
• includes all classes, interfaces, functions and constants, as they are all covered by namespaces
• includes the global namespace, so we can distinguish between relative and global

------
References to classes, interfaces, functions, and constants in documentation blocks should include the fully-qualified namespace (starting with a backslash). This applies whether the item is mentioned in documentation text, or an @see, @param or @return line, and it applies whether the class mentioned is in the current namespace or another one. If the item is in the global namespace, it should be preceded by a slash. In descriptive text, where it is not ambiguous or unclear, qualified (relative) names can be used.

Example:

/**
  * Namespace declaration
  * Note, that d.o is stripping slashes from qualified namespaces
  */
namespace Space\One\Foo;

/**
 * Does something really cool.
 *
 * Here we talk about some other method Stuff::whatever(), and about
 * \Space\Two\Bar::something().
 *
 * @param \Space\One\Foo\Stuff $stuff
 *   Description including something about the Stuff class.
 *
 * @return \Space\Two\Bar
 *   Description including something about the \Space\Two\Bar class.
 */
function baz(\Space\One\Foo\Stuff $stuff) {}

There's another problem, implicit in the example above. In its current configuration, d.o will strip slashes from namespaces which aren't fully qualified.

What does concern me about any of the proposals, is that, in order to distinguish between relative and global requires add a backslash to all \global items in @param or @return blocks, which is just a lot of work.

The d.o problem will be resolved by #1481162: Update prod to PHP 5.3.

I think #18 misunderstood my issue in #17. "Description including something about the \Space\Two\Bar class" I would rather see as "Description about the Bar class", since it's quite obvious which Bar you're referring to and far less likely to break on the 80-character limit for comments.

Ah good, thanks, I looked for an issue but couldn't find one...

#19: I understood that part, and I agree, in the descriptive text, where it is clear and the IDE doesn't care, you should be able to avoid the whole namespace. Thats the last sentence in the wording I proposed.

RE #18 - I have some serious problems with that proposed standard...

But I was realizing that we need to agree on the principles before we really try to write a standard. Here are the questions I think we need to agree on answers to, before we finalize the exact wording and examples for the standard:

Basic questions to answer

Notes:
- "items" in the following means: classes, functions, constants, etc.
- The answer to each question could be No, Require, or Suggest.

a) In @param/@return types, should we require/suggest that class/interface names include the fully-qualified namespace starting with backslash? [This question pertains only to the class/interface name immediately after the @param/@return tag. (Ex: @param \This\Space\Thing\Foo $foo)]

b) Whenever we are using namespaces in documentation in general, should we require/suggest that they be the fully-qualified namespace (starting with a backslash)? (as opposed to allowing the namespace to not start with a backslash)

c) When referring to items in the global namespace in documentation, should we require/suggest that they be preceded by a backslash? (For example, whenever we refer to drupal_render() it should start with a backslash.)

d) When referring to items within the declared namespace of the current file in documentation, should we require/suggest that they include the namespace?

e) When referring to items in a namespace other than the declared namespace of the current file in documentation, where the namespace is mentioned in a "use" declaration in this file, should we require/suggest that they include the namespace?

f) When referring to items in a namespace other than the declared namespace of the current file in documentation, in the rare case where the namespace is *not* mentioned in a "use" declaration in this file, should we require/suggest that they include the namespace?

g) When referring to items in namespaces in @see lines, whether the current or a different namespace, should we require/suggest that they include the namespace? (alternatively, @see lines would follow the generic documentation rules for namespaced items)

h) When referring to items in the global namespace in @see lines, whether or not the current file has a namespace, should we require/suggest that they be preceded with a backslash? (alternatively, @see lines would follow the generic documentation rules for global namespace items)

[EDIT: I had two item (e) questions here!]

My answers to the questions in #21:
a) Yes (for IDEs).
b) Yes, if we're using namespaces, they should always be fully-qualified I think.
c) Emphatic NO! No backslashes for global items.
d) Tentatively no (too much clutter to always use namespaces in docs).
e) Tentatively no (still too much clutter, and PHP can figure out the class, so humans and the API module should be able to also).
f) Yes (this should be rare, but if it's not in a use, we should fully namespace it).
g) No. The only reason this should be necessary (@see always having namespace) would be for the API module, but (see above) I don't think it's necessary.
h) Emphatic no, see (c).

[Note: The edit just fixed typos. I must not have been awake this morning.]

I don't want to make docs harder to read, but adding namespaces are clutter - thats unavoidable - and we have to consider accuracy. So here's my answers to your questions.

a) Yes
b) Yes
c) Yes. A single backslash indicates a global item, and it disambiguates them from relative items. Including it is not personal choice. If you use it, then its a fully qualified name. If you don't use it, then it's just a qualified/relative name. That makes no difference if you reference something which only exists in the global namespace, but if it exists in the current namespace as well then you have a problem, as you've reference the wrong thing. A doc generator might be able to work that one out, but a human could get it wrong quite easily. At the very least, we should start introducing them, over time we'll reduce the number of relatively referenced global namespace references. The example I provided in #10 illustrates this.
d) Optionally no, but if it's not clear in the documentation, use the FQ name.
e) Yes. There may be multiple use statements, some with aliases. If these are being used to map namespaces with identical item names, then its important that its clear which items are being referenced. The exception is where the FQ name is referenced in a @param or other reference, such that its clear. Also, we don't want people to have to keep jumping to the top of the file just to work out what namespace they are looking at. I don't agree that "if PHP can do it then so can we". That might be technically true, but it doesn't necessarily make the docs easier to read.
f) Yes. Same as (e).
g) Yes. Same as (e). Additionally, I would have thought it makes docs easier to generate, but at the very least, if I decide to go and @see that item, I have the fully qualified name in front of me, which helps me find it.
h) Yes. Same as (h)

The aim of this exercise should be to produce clear, accurate documentation. Fully qualified namespaces seem long and difficult to read initially, but once you get used to reading them, they make documentation much clearer. It seems easier to me to have a rule which requires FQ names by default, but makes them optional where IDEs do not require them, and it is clear what is being referred to. That was the basis of my proposal.

Thanks for responding! We need more opinions... Obviously xtfer and I do not agree on these answers. :)

One other thing (and I led the way by being ambiguous in my answers in #22): we need to clarify required vs. suggested. In all of my answers I would say "Everything that isn't required is forbidden" -- in other words, I don't want to leave room for personal choice in the standards. So when I said "yes", I meant "require".

RE (e) - One more thought... My feeling is that we should follow, as much as possible/practical, the same rules in documentation that are used in our PHP coding standards (and for the PHP interpreter). So if the code requires a namespace to be provided, we should provide it, and if not, we shouldn't. Therefore, if use() disambiguates a class name for code, I think we can/should also leave the namespace out of the documentation.

A) Yes. (At least in NetBeans, it's mandatory in the @return if you want auto-completion, and we want auto-completion.)

B) No.

C) No. My backslash key would wear out. :-)

D) No.

E) No (or suggest no, at least)

F) Suggest

G) Yes

H) No

Generally speaking, I favor using namespaces in docs iff it's in a "machine targeted" part of the documentation, and if the thing being referred to has a non-namespace. Otherwise, short name.

RE the last comment in #25...

As the maintainer of the API module, I would say that *any* reference to an item (class, function, etc.) in documentation is "machine targeted", since the API module tries to turn all such references in documentation into links. There is zero difference between the process used to make links when the item is referenced in @param, @return, @see, or the general documentation body. The API module also makes the links you see in code listings on api.drupal.org, using pretty much the same process as in documentation, and that will definitely need to be aware of the use/namespace declarations in order to make the right links (it isn't right now, but that is a separate issue).

Anyway, what I'm trying to say is that for purposes of "machine targeting" in the API module, there is no reason that the documentation links cannot use the same namespace conventions that are used in code, and there is no difference between what is needed in @see, @param, @return, or the general documentation body (or code, for that matter). So, for purposes of api.drupal.org and the API module, we would only need to use namespaces if referring to an item that was not in a namespace/use declaration in the file.

The other "machine targeting" would be for IDEs, and apparently the only relevant spot is the @param/@return types, where we would need to use a fully-qualified namespace along with the class/interface name, starting with a backslash.

I'm also not sure what "the thing being referred to has a non-namespace" means in comment #25?

IDEs are the machine that I'm talking about, specifically. I know we can code api.module to do whatever we want, but in general I see the thing immediately after a @foo as "programs will pay attention to this, and humans may too", and everything else as "only humans will pay attention to this". (Just because api.module can read something doesn't mean it is targeted at it, specifically.)

As for non-namespace... I have no idea what I meant. :-) I think I meant to say non-empty namespace, vis, it's not global. Vis, not doing \DateTime, \stdClass, etc.

As far as I know, the only @tags that IDEs seem to be aware of are @param and @return (and maybe @var for the type of class member variables?), where they look to what comes immediately afterwards to be a valid type (int, string, class name, etc.), and apparently at least some of them want it to be a fully-qualified namespace. At least, that is all that people who use IDEs have complained about... I haven't seen anyone talking about @see, @link, etc. for IDEs.

Yes, @param, @return, and @var are the ones that matter for code completion. Those apparently need to be fully qualified to parse properly. (We still need to do a survey to verify that properly, though.) Therefore, those are the things I'd like to see as fully qualified names. For other @tags, I am impartial I suppose. For body text, no machine but api.module is going to be reading it, and it's way easier for a human if it's not a 70-character long name, so I'd rather we NOT do it there.

I'm kind of inclined to agree (mostly) with Crell. A proposed policy for documentation, which I think can be stated fairly simply:

---
Definition: In the following, "item" means a class, function, etc.
a) When using a class or interface name to indicate the data type for @param, @return, or @var, prefix with the fully-qualified namespace name (starting with a backslash), unless the class/interface is in the global namespace.
b) Elsewhere in documentation, omit the namespace if it is clear (within the use/namespace declaration context of the file) what namespace the item is in.
c) If you feel that the documentation needs the namespace prefixed for clarity, use the fully-qualified namespace (starting with a backslash).
d) Never prefix items in documentation that are within the global namespace with a backslash.

Example -- given that classes Foo, Bar, and Thingy are in the A\B\C namespace, and class Baz is in the X\Y namespace:

namespace A\B\C
use X\Y;

/**
 * Represents the data associated with foo.
 *
 * A Foo object can be used to do something interesting with Bar objects, but if
 * you need to do something else, you might need a Baz object. On the other hand,
 * the \J\K\L\Whatever class might be needed in some cases.
 *
 * @see Bar
 * @see Baz
 * @see \J\K\L\Whatever
 */
class Foo {
  /**
   * Some kind of information stored on this class.
   *
   * @var \A\B\C\Thingy
   */
   public $thingy;

  /**
   * Takes some kind of action.
   *
   * @param \A\B\C\Bar $bar
   *   The bar that this action depends on.
   *
   * @return \X\Y\Baz
   *   A baz that contains the returned information from this action.
   */
   public function some_action(Bar $bar) {
   }
}

---

Notes on why I think this might be the best policy:
- (a) - needed for at least some IDEs (that was the reason this issue was filed originally).
- (c) - more consistent with (a), and it will lead to fewer errors if we have a clear policy that says "whenever you use a namespace, start it with a backslash".
- (b) and (d) - save typing and clutter.

Thoughts?

The public $thingy in the example should be protected $thingy, so we don't give anyone the wrong idea. :-)

Other than that, #30 looks great to me. That should give IDEs the information they need, and trust humans to be able to read context like humans are so good at.

Not marking RTBC yet to allow others to comment, but I'm overall happy with #30. Thanks, Jen!

I'm mostly happy with this, its less prescriptive about not using namespaces and focuses on clarity, so it solves some of my issues...

I'd like to address the global namespace, however...

d) Never prefix items in documentation that are within the global namespace with a backslash.

I wonder if this will confuse people. If you have both \Baz() and A\B\Baz(), then prefixing the global namespace is probably desirable. We can rephrase it to remove the definitive "never", and allow a bit more flexibility...

d) Unless similar name occurs in the current namespace, prefixing items within the global namespace in documentation is optional.

Also, at least in PHPStorm, @param, @return and @var need the fully-qualified namespace, whether its global or not, so...

a) When using a class or interface name to indicate the data type for @param, @return, or @var, prefix with the fully-qualified namespace name (starting with a backslash), unless the class/interface is in the global namespace.

becomes...

a) When using a class or interface name to indicate the data type for @param, @return, or @var, prefix with the fully-qualified namespace name (starting with a backslash).

I want to say to #30 "Even easier to document is 'Always use the fully-qualified name.' Period." I'm sure i'm missing a cluestick, however. But I can't read this issue right now. So it'd be great if this issue had an up-to-date issue summary that documented the options and pros/cons list so the next me out there could make an informed opinion, since you're asking for more people to chime in.

RE #32 - So you're saying that IDEs cannot get the class names from param/return in *any* of our D7 documentation, where everything is in the global namespace and none of it has backslashes? That seems unlikely to me, and I'd like confirmation.

RE #33 - yeah, we need an issue summary, sorry! If someone has time... otherwise I'll see what I can do later today.

#34: In D7, where its all global, it makes no difference, but its not a good test case, because it has no namespaces.

The problem arises where you are in a namespace already and you try to reference something in the global namespace - that will fail, because you've actually specified a relative path.

Lets be clear: if it doesn't have an initial slash, it's a relative namespace path. While that will work when actually using the items in PHP (in some cases) it wont work necessarily for @ values, and you are relying on the IDE to "know" that you intended it to be global, which is going to come down to implementations of IDEs. We don't want that.

So, you can't just say "if its a class in the global namespace you don't need an initial slash", because that ignores the context of the reference, so unless we specify some moderately complex rules for when to include it, we are stuck with "always use fully qualified names in @ values", which we can be reasonably sure will not break.

OK, here's a new standard proposal. Hopefully all the concerns have been addressed this time...

---
Definition: In the following, "item" means a class, function, etc.
a) When using a class or interface name to indicate the data type for @param, @return, or @var, prefix with the fully-qualified namespace name (starting with a backslash). If the class/interface is in the global namespace, prefix it with a backslash.
b) Elsewhere in documentation, omit the namespace if it is clear what namespace the item is in (within the use/namespace declaration context of the file).
c) If you feel that the documentation needs the namespace prefixed for clarity, use the fully-qualified namespace (starting with a backslash).

Example -- given that classes Foo, Bar, and Thingy are in the A\B\C namespace, and class Baz is in the X\Y namespace:

namespace A\B\C
use X\Y;

/**
 * Represents the data associated with foo.
 *
 * A Foo object can be used to do something interesting with Bar objects, but if
 * you need to do something else, you might need a Baz object. On the other hand,
 * the \J\K\L\Whatever class might be needed in some cases.
 *
 * @see Bar
 * @see Baz
 * @see \J\K\L\Whatever
 */
class Foo {
  /**
   * Some kind of information stored on this class.
   *
   * @var \A\B\C\Thingy
   */
   protected $thingy;

  /**
   * Takes some kind of action.
   *
   * @param \A\B\C\Bar $bar
   *   The bar that this action depends on.
   *
   * @return \X\Y\Baz
   *   A baz that contains the returned information from this action.
   */
   public function some_action(Bar $bar) {
   }
}

---

I'll also update the issue summary.

Ok, my question still stands though. Why would we not just fully-qualify it everywhere, if we have to fully-qualify it some places? In other words, how do I know if I'm dealing with a b) situation or not? That's unclear. If there's a technical reason, we should document it. If it's a personal preference/arbitrary feeling of better readability reason, we should lean towards consistency instead IMO since there definitely are technical reasons for using fully-qualified names in those a) places.

RE #37 - Most people who commented above find "fully-qualified everywhere" cumbersome to read/write, and it leads to problems when trying to fit namespaced class names into 80-character one-line summaries.

But that is a good point -- maybe we need to rewrite the standard so that it's not personal preference deciding between (b) and (c). One iteration above basically said "If it's in one of the use/namespace declared namespaces, don't prefix. If it's outside, prefix it.". That would at least be definite...

In any case, I've updated the issue summary with the status of the issue up through comment #36.

I found the example in #36 confusing because most of the docblocks don't have information anywhere within them that tells me Baz is in X\Y. The code has "use X\Y" at the top rather than "use X\Y\Baz" (which may be a mistake), but even with the latter I'd still have to scroll up to the top of the file to figure it out, and if I'm reading it on api.drupal.org that might not be an option.

Also, the standard proposed in #38 would mean that all references to \J\K\L\Whatever always have to use the fully-qualified namespace (even if there are 5 of them in a row), so you'd still have cases with cumbersome repetition.

What if we said that within a single docblock, the first reference to a class should use the full namespace, but subsequent ones can use the abbreviation? That would be similar to how we do it in human languages (e.g., in newspaper articles you'll usually see them refer to "President Barack Obama" in the first sentence of the article, but after that it's just "Obama").

I also found it confusing that @see is using different rules than @return/@param/etc. If we have to always use the fully-qualified namespace for the latter ones, it would make sense to me to apply the same rules to @see as well (even if it's not technically required).

I think it's easier to remember the rule if it's simply "always use fully qualified namespace in one of the @-lines" than if there are different rules for different ones.

RE #40 - the only reason we need fully-qualified namespaces for anything at all is that IDEs read @return/@param/@var (and as far as I know, nothing else), and they need fully-qualified namespaces. Other than that, the API module and human readers should not care...

RE #39 and the standard in general... No one is really happy with any of the standards ideas that can be written down in any kind of concise form. The only really concise rule is "always use the fully-qualified namespace", which leads to excessive clutter. But beyond that, everything gets into a long list of exceptions that make it difficult to comply with the standards.

So I'm really not sure what we should do. Standards are difficult... sigh.

I think what I proposed could be written concisely (well, relatively so), something like:

Use the fully-qualified namespace the first time a class is referred to in a block of documentation, and whenever it is used in an @declaration (e.g., @return, @param, @see). Otherwise, the namespace may be omitted.

So example code would be something like:

namespace A\B\C;
use X\Y;

class Foo {
  /**
   * Takes some kind of action.
   *
   * The \A\B\C\Foo class has several methods that perform actions, but in most
   * cases this is the one you should call. However, if your Foo object is pink with
   * purple polka dots, you may need to call one of the other methods instead,
   * and if your Foo object is green, don't call any of them because it will lead to
   * the destruction of the Internet.
   *
   * @param \A\B\C\Bar $bar
   *   The Bar object that this action depends on.
   *
   * @return \X\Y\Baz
   *   A Baz object that contains the information returned from this action.
   *
   * @see \A\B\C\Foo:someOtherAction()
   * @see \A\B\C\Foo:yetAnotherAction()
   * @see \J\K\L\Whatever:destroyTheInternet()
   */
   public function someAction(Bar $bar) {
   }
}

Regarding @see, I realize that's it not technically required; I'm just saying that I would probably find it easier (as a documentation writer) to remember if all the @-declarations had the same standard. I could get used to it either way, though.

RE #42 - I'd be OK with that standard. It does seem like a good balance between the clutter factor, the complex standards factor, and the make-sure-to-have-enough-information factor. I'm not sure about the "may be omitted" though -- I'd prefer to just say "should be omitted" or even better "Omit the namespace", to make it clearer.

One other thing that is missing from the standard is whether or not the backslash is to be used with global-namespace items. I am not sure whether we've agreed upon that or not.

So... here's a slight rewrite:

Use the fully-qualified namespace (starting with a backslash) the first time a namespaced class, interface, or other item is referred to in a block of documentation, and whenever it is used just after an @tag (@return, @param, @see, etc.). Otherwise, omit the namespace.

My concern with "first use" is that it can still lead to block text breaking wrapping. Basically if you ever have a need to mention a class name in the short-description of a method/class/whatever, you are 100% guaranteed to break the 80-character limit before you say anything useful.

Coming here from #1290694: Provide consistency for attributes and classes arrays provided by template_preprocess() where we weren't sure, what the current/future standard for class constructors is, i.e.

  /**
   * Constructs a DatabaseStatementBase object.
   *
   * @param DatabaseConnection $dbh
   *   Database connection object.
   */
  protected function __construct($dbh) {
    // Function body here.
  }

(This is from http://drupal.org/node/1354#classes)

But you could just as well argue for "Constructs a \Drupal\Component\Database\DatabaseStatementBase object." (or whatever the namespace is). Just wanted to mention that, whatever comes out as consensus here, a class constructor could/should be added to the example documentation.

RE #45 - To me, requiring the full namespace there is ridiculous, and illustrates the clutter of the proposed policy... I think we should really go back to the idea of only requiring the namespace if it's outside of the declared "namespace" line of the file.

RE #46 - Agreed. Even if the class is outside the declared namespace, as long as there is a use statement for it, we should not need to declare the full namespace in the docs. If the namespace for the class is changed, we don't want to have to update the namespaces for it throughout the docs.

As an example, have a look at RepeatedPass.php. Even though ContainerBuilder is in a different namespace, it does not re-declare the namespace for ContainerBuilder in the process() documentation. Just uses @param ContainerBuilder $container, since the namespace has already been used.

namespace Symfony\Component\DependencyInjection\Compiler;

use Symfony\Component\DependencyInjection\ContainerBuilder;

    /**
     * Process the repeatable passes that run more than once.
     *
     * @param ContainerBuilder $container
     */
    public function process(ContainerBuilder $container)
    {
        $this->repeat = false;
        foreach ($this->passes as $pass) {
            $pass->process($container);
        }

        if ($this->repeat) {
            $this->process($container);
        }
    }

We already have the namespace declared for ContainerBuilder in the use statements, why declare it multiple times throughout the file.

If it is not in the use statements however, we probably would want to have the namespaces so we know which class we're referring to.

The only problem is that while you and I agree, and the API module can cope with this, and it's very clear to human readers and a lot less cluttered, apparently IDEs cannot cope with having param/return types missing the full namespace starting with a slash. :(

Working with namespaces is quite confusing right now. No global prefixes in use statements, global prefixes in some hook parameter docs, but not in most of them not. Then my IDE (phpstorm) keeps complaining about not fqdn namespaces (=missing the initial \) in files that are already in a different namespace, for example Drupal\entity\EntityInterface in the namespace Drupal\entity.

I think the IDE is right as without the missing \ it's relative, so can we conclude that at least to do

a) When using a class or interface name to indicate the data type for @param, @return, or @var, prefix with the fully-qualified namespace name (starting with a backslash). If the class/interface is in the global namespace, prefix it with a backslash.

*now*?

I am happy with #42. I think its a good deal.

But according to http://php.net/manual/en/language.namespaces.rules.php, the point N°3 tells: Inside a namespace, all qualified names not translated according to import rules have the current namespace prepended. For example, if a call to C\D\e() is performed within namespace A\B, it is translated to A\B\C\D\e().

So that mean an IDE should be able to respect this rule. Well, at least eclipse support it [ref], and it seems NetBeans too [ref] but I havn't tested the later.

Concerning the @see, eclipse makes a clickable link when you hover over the hint. So that's a good practise to keep the fully qualified class name when external to the imported namespace.

It seems to be that there is an consensus found on this issue.
Regarding the 80 chars doc length, you could even have namespace+classnames which are > 80 chars in that case
you should break the line after it. For example this really happens easy if you have something like

/**
 * Overrides Drupal\views\Plugin\views\display\DisplayPluginBase::defineOptions().
 */

but i think that's okay if it is avoided where it is possible.

Note somewhat related issue #1614186: Coding standards for using "native" PHP classes like stdClass in namespaced code... I think we probably need to update the standards here to be in line with that issue?

I think the proposal makes sense. Just to be sure, the following would be the correct way to declare a @file directive for a class file, right?:

/**
 * @file
 * Definition of \Drupal\Core\Plugin\Foo.php.
 */

And also, in case the namespace being referred to is clear:

namespace Sport;

use Sport\SportInterface;

class Football implements SportInterface {

  /**
   * Implements SportInterface::play().
   */
  public function play {
    ...
  }
}

Somewhat related, is there a standard on how the use statements should be ordered? Alphabetical?

The extra use statement in #54 isn't necessary.

Lars: We discussed that in some past issue, and at the time the general feeling was "meh". :-) I've been tending to put all Symfony classes first in one block, grouped by component, and then all Drupal code, roughly alphabetically, but I've not been completely consistent about it.

Re #56, that's true, thanks. Can I interpret your lack of comment on the rest as approval that the PHPDoc using an absolute namespace for @file and no namespace at all for "Implements ..." is correct?

Thanks for your comment @tstoeckler. I believe that a fully qualified path is necessary for the @file, 'Implements...', @param and @return directives.

I also find it quite disconcerting to see a series of use statements in a random order. That is why I asked the question in #55.

I think/hope that #54 is correct. ;)

However, on #53, the fully-qualified class name in @file should not be rooted (i.e., no leading \ backslash).

Additionally, and I will totally agree that the amount of PSR-0/namespace coding standards issues is getting hilarious, the @file description is about to change from "Definition of" to just "Contains" in:
#1392754: Comply with new documentation standards for @file for namespaced class files

The placement and order of use statements should be an own issue (meh! ;)), so we can finally get this off the table. Thus, I've created:
#1791928: [policy] Coding standards for "use" statements

Speaking of... adjusting status.

However, on #53, the fully-qualified class name in @file should not be rooted (i.e., no leading \ backslash).

The example in the issue summary actually uses a rooted namespace in PHPDoc, so...?! Could someone clarify?

RE #53 -

/**
* @file
* Definition of \Drupal\Core\Plugin\Foo.php.
*/

I don't think it should have .php at the end?!? I'm not sure about the fully-qualified (starting with backslash) vs. not...

Re #61: Right, the .php file ending is non-sense.

Regarding fully-qualified or not: I think "Definition of ..." is just another example of a namespace in a documentation header, so I had thought that

c) If you feel that the documentation needs the namespace prefixed for clarity, use the fully-qualified namespace (starting with a backslash).

from the issue summary applies. If that is not the case we should definitely document that explicitly (i.e. "use fully-qualified in PHPDoc but not in one-line summaries", or whatever that standard is...)

See also: #1614186: Coding standards for using "native" PHP classes like stdClass in namespaced code

Edit: Totally commented on the wrong issue. But http://drupal.org/node/608152 should probably have a link to the namespace handbook doc for namespaces.

#65 is taken care of.

RE #64, we have not yet come to an agreement here on a standard for the use of namespaces in documentation in general... I would like to see us agree before moving forward with patches.

But I do think we have agreed that in @param, @return, and @var when specifying a class, it does have to be fully-qualified (for IDEs if nothing else), and in our code namespace standards, we have definitely agreed that global namespaced classes have to start with a backslash, so that much I think is not in question.

I would suggest *not* making patches yet, due to #1809930: [META] Many core class names violate naming standards -- many of our class names are going to need to be changed, so patching the docs now seems premature. If you want to do patches, what we've done on other issues is make sub-issues covering one module each or a subset of include files.

Anyway... Can we come to an agreement? I think we have basically three proposals on the table. Let's see votes for each -- I will put these three proposals in the issue summary, as the one there is not quite consistent with our coding standards for namespaces...

Proposal 1:

a) When using a class or interface name to indicate the data type for a @param, @return, or @var, prefix it with the fully-qualified namespace name (starting with a backslash). If the class/interface is in the global namespace, prefix it with a backslash.
b) Elsewhere in documentation, omit the namespace if the class/interface is within the use/namespace declaration context of the file.
c) If you refer to a class/interface that is not in the current file's use/namespace declaration context, or that is in the global namespace, prefix it with the fully-qualified namespace name (starting with a backslash).

Proposal 2: [same as proposal 1, but applying to all @-tags]

a) When using a class or interface name immediately after any @-tag in documentation, prefix it with the fully-qualified namespace name (starting with a backslash). If the class/interface is in the global namespace, prefix it with a backslash.
b) Elsewhere in documentation, omit the namespace if the class/interface is within the use/namespace declaration context of the file.
c) If you refer to a class/interface that is not in the current file's use/namespace declaration context, or that is in the global namespace, prefix it with the fully-qualified namespace name (starting with a backslash).

Proposal 3:

When using a class or interface name anywhere in a documentation block (/** */), prefix with the fully-qualified namespace name (starting with a backslash). If the class/interface is in the global namespace, prefix it with a backslash.

For the record, I am in favor of Proposal 1. To be consistent with our coding standards for code lines, we would actually never require documentation mentioning classes in the namespace context of a file to have namespace prefixes at all, but apparently IDEs do need these prefixes. But that only applies to param/return/var, so my feeling is that to avoid unnecessary typing and clutter, Proposal 1 is the best. And I think it is clear enough that it can be followed.

Any other opinions?

I vote for option 2. Specifically because of @see, which many people have found useful in IDEs.

Also, at the risk of stating the obvious, if this standard is adopted, the following, which is found in many, if not most core class files, is *incorrect* (it is missing a leading backslash):

/**
 * @file
 * Contains Drupal\Core\Entity\Entity.
 */

Edit: The latter is true for any of the three proposals.

added issue summary

I've updated the issue summary with these proposals.

RE #68 - That is correct. We would need to patch the @file declarations.

And I'm OK with adopting option 2 -- it's probably clearer and easier to follow than option 1 without producing too much clutter. Any other opinions?

Options 2 sounds good to me. We should be consistent with all our @tags, so let's adopt it for all of them. That makes it a lot easier to remember the right rules also.

I am in favor of proposal #2. Consistency with all @ directives makes it easier to remember when developing, changing or reviewing any documentation.

I also would like to see some clarity on the ordering of @use directives. After reviewing many files as part of the #1310084: [meta] API documentation cleanup sprint initiative, I can safely state that core is all over the place with regard to the organization of multiple @use statements.

RE #71 - please do not introduce new questions to this issue (ordering of use statements). If you want to discuss that as a standard, file another issue (drupal core / documentation / tag "coding standards").

I was not raising a new issue. See #58 above.

I agree with proposal #2. I don't think it's necessary to change the wording, but I do think it's okay to omit the namespace inline in the docblock text if the full namespace is already mentioned. E.g., I think these things are fine in namespace Drupal\frog:

 * @param \Drupal\bird\Heron
 *   The Heron object representing the heron trying to eat the frog.

/**
 * Eats a bug.
 *
 * Note that not all implementations of \Drupal\bug\BugInterface are
 * safe for frog consumption. Be sure to check BugInterface::isPoisonous().
 *
 * @param \Drupal\bug\BugInterface $bug
 *   The bug to eat.
 *
 * @return bool
 *   TRUE if the bug was eaten successfully, or FALSE otherwise.
 */

@Lars Toomre, the question is out of scope for this issue, which is about documentation. The fact that you've brought it up several times in this issue does not make it in scope for this issue. Please open a separate one. Thanks!

Update with latest proposals and summary of opinions

I strongly recommend against patching this wholesale before Dec 1 possibly even Apr 1 -- new patches should adopt it but a carpet bombing patch affecting most of core is not to our advantage.

+1000.

Jennifer asked for this to be assigned to her.

Is this now a coding standard? My impression from #77 was that it was now approved and a coding standard. Did I miss something?

Patience, patience, patience!

So, this has now been sitting in RTBC long enough, and I just added it to node/1354. I also updated the page so that the examples follow our standards, such as this new one and the one about "param/return need types". whew!
http://drupal.org/coding-standards/docs#namespaces

The next thing would be to patch core so it complies. I think we need a meta-cleanup-issue for that but I need to go offline now so I cannot file it... Anyway, the standard is adopted and docs are updated. Thanks all!

We might also need a coder issue to scan for this? Should not be too hard to regexp.

So I'm setting this back to active until:
- meta issue is filed
- coder issue is filed
and I think I have time to update the issue summary with this status update.

Marked Proposal 2

The coding standard and example don't explicitly mention which rule now applies to the default Implements x and Overrides y docblock sentences. Can the example be updated with such a method? Should they contain the full namespace or not?

Also, see #78. Please do *not* start an effort/meta issue to clean this up now. We partially did that already multiples times and it does get messed up anyway when classes are moved around (or standards are changed, which currently seems to be happening frequently ;)). And we are still moving classes around *a lot*. Not to mention that it would result in lots of conflicts.

RE #82 - good point, and we should also clarify what should happen to all of those @file lines added for PSR-0 that say something like "Defines Full\Namespace\Without\Slashes\Foo". That's clearly wrong by our current standards (it should start with backslash if it's the namespace)...

So, it seems that if class A implements/extends B, then there must be a use B declaration (or else B is in A's namespace). So by the standards we've agreed upon:
- @file and Implements/Overrides lines should NOT include the namespace.

Does everyone agree that this is OK to add to the standards example (and as a note to the documentation of the standard)?

Any thoughts on #83? It seems like to be consistent with the standard we've adopted at:
http://drupal.org/coding-standards/docs#namespaces

a) @file lines that say "Defines (classname)" should not include the namespace.
b) One-line descriptions that say "Overrides (classname)::(methodname)" should not include the namespace.

Does anyone have an objection to adding these notes to the standards?

Defines Full\Namespace\Without\Slashes\Foo

The namespace is already defined by namespace Full\Namespace\Without\Slashes; above, so why have it in twice. If a namespace changes, then the patch will end up being twice as large. We should add a note to omit the namespace to the docs.

#84/#83 make total sense and are really just a matter of consistency at this point.
One thing, though: If we are already changing that part of the standards, the @file declaration should be Contains Foo. instead of Defines Foo. per our agreement reached elsewhere.

OK. I'll put this at RTBC and leave it for a few days to make sure there are no objections, then update the docs with these notes (and also make sure our docs and namespace standards pages do not violate these standards in their examples).

I disagree. I use the namespace from the @file docblock all the time to copy and paste the full classname. I agree with not repeating the full namespace over and over inline in documentation, but the @file appears before the namespace and use statements.

Furthermore, it's already in 1500 classes in core. Can we just stop changing that line already? (It was changed from "Definition of" to "Contains" four months ago for no compelling reason and only about 10% of classes are correct there at this point.)

I also think it's useful in "Implements" and "Overrides". Basically, I shouldn't have to hunt through the codebase to figure out which class or interface the method is on.

Edit: Like, there's totally no point to even having the Implements/Overrides docblock if it doesn't tell me where exactly the benighted method is.

Sounds like very valid arguments to me. @file is the only place where the current class is available with the full namespace for copying, have used this before as well.

OK....

So you are both saying you want to amend the standards we previously adopted (http://drupal.org/node/1354#namespaces) so that where it currently says:

When using a class or interface name immediately after any @-tag in documentation, prefix it with the fully-qualified namespace name (starting with a backslash). If the class/interface is in the global namespace, prefix it with a backslash.

(then the current standard says basically "elsewhere, omit the namespace if it's in a use/namespace declaration")

It should now say:

When using a class or interface name immediately after any @-tag in documentation, in the standard @file description line for a PSR-0 class ("Contains \The\Namespace\ClassName."), or in a standard method implements/override description line ("Overrides \The\Namespace\ClassName::methodName()."), prefix it with the fully-qualified namespace name (starting with a backslash). If the class/interface is in the global namespace, prefix it with a backslash.

Does that capture what you would like to see happening? I'm OK with that idea, though it seems complicated. Maybe we should just go back to "Always use the namespace"?

Oh and one note on all the "Contains" @file lines -- I don't think any of them currently use a backslash at the beginning of the namespace, so they will all need to be patched anyway. One thing everyone on this issue agreed with is that if you do use namespaces, they should definitely start with backslashes...

Edit: Like, there's totally no point to even having the Implements/Overrides docblock if it doesn't tell me where exactly the benighted method is.

I'd disagree here. It's quite unnecessarily repeating the namespace over and over again if you are implementing an interface if it is already imported anyway.

If it is not yet imported, I'd even be open for importing it only because of the possibility to shorten the docs. I found it very cumbersome to write or look up the whole namespace for each method I am implementing, whereas writing the unqualified class name is faster and simpler. Also, when reading the unqualified namespace it's faster to grok (less visual bloat). Documentation that is less cumbersome to write, also means more documentation being written in non-core usage.

That case of classes implementing an interface which is not denoted there reminds me of a related but a bit off-topic issue: Do we want to document which interface the class implements as following? This would make clear what the class' purpose is.
So what about that:

/**
 * Implements \Drupal\core\Entity\EntityInterface.
 */
class Node extends Entity {

  /**
   * Implements EntityInterface::id().
   */
  public function id() {
    return $node->nid->value;
  }
}

So...

I do feel like this idea of redoing the docs standard is trying to undo all of the discussion we had previously about namespaces in documentation. Previously, we decided that in general, we didn't want the namespaces cluttering up documentation, but in deference to IDEs, we would require them in @param/@return/@var (and for consistency, we decided to require them immediately after all @ tags).

I still think that all of those arguments above apply and I'm not excited about adding more requirements to use the full namespaces in documentation, because it takes a lot of typing and the whole idea was that the context was usually clear.

Also, I don't like requirements with a lot of exceptions -- we have plenty of those (just look at the length of node/1354 already!!) ...

So.

I think we should either:
a) Change our minds and require the namespaces everywhere (UGH!!!) or
b) Leave the requirements as they are, implying that we don't want them in Implements/Overrides and in @file lines or
c) Perhaps make 1 more exception for the @file line.

My vote goes to #95.c) — i.e., one exception for @file (because that's really really useful) and treat the entire rest as IDE-flaws/bugs (which should be able to properly resolve all namespaces anyway; if they're not, then they're not any more helpful than a plain text editor).

There's only one case that I think @fago alluded to in #94 and into which I ran very recently: Considering this class hierarchy:

class ConfigEntityBase extends Entity;
class NodeType extends ConfigEntityBase;

and when NodeType overrides a method of Entity, which isn't overridden by ConfigEntityBase, then this context is factually not apparent for non-IDE users, because Entity does not appear at all within NodeType.php. However, if I understand the current proposal correctly, it would be denoted with the following, and I think that provides sufficient context:

 * Overrides Entity::whatever().

As a non-IDE user, I'd be totally fine with that. OO code generally requires some more "manual lookups and grepping" from my perspective, and that only gets insane when code is abstracted too much (Views has been a good example for too much abstraction in the past, but I'm not sure whether that is still the case with the code in core/HEAD).

Yes, we always say "Overrides ClassName::methodName()", so I think that would alleviate any confusion. And we also have in our current documentation standards:

If you refer to a class/interface that is not in the current file's use/namespace declaration context, or that is in the global namespace, prefix it with the fully-qualified namespace name (starting with a backslash).

So if Entity was not part of any use/namespace context of the file, we would require the namespace to be given.

My IDE (eclipse) knows that @return Entity is a Drupal\Core\Entity\Entity as I import the package name in the 'use' declaration. So I don't need the FQCN (Fully Qualified Class Name) to be written in the doc block to be treated as an Entity.

And sun is right, if an IDE can't infer the FQCN from use declaration, then it would be wise to change it :) So let's not treat this as a requirement for writing long and boring FQCN. Moreover, if we think about maintainability, it does not scale well when we'll do refactoring: if you move a component from a package A to a package B, you'll have to re-write all the docblocks referencing it whereas if you was just using class name, updating the 'use' declaration would have been sufficient.

I think we should stop writing the FQCN in doc anyway, because:

1. IDE can infer it: as they do for type hint.
2. If we refactor a component package and move to a new namespace, we need to update the use declaration, plus the docblocks.
3. Symfony does not write the FQCN in docblock, they use the class name only.
4. If we are not writing FQCN in PHP method signature (see below), why should we do it in the doc ?

<?php
/**
     * Constructor.
     *
     * @param SessionStorageInterface $storage    A SessionStorageInterface instance.
     * @param AttributeBagInterface   $attributes An AttributeBagInterface instance, (defaults null for default AttributeBag)
     * @param FlashBagInterface       $flashes    A FlashBagInterface instance (defaults null for default FlashBag)
     */
    public function __construct(SessionStorageInterface $storage = null, AttributeBagInterface $attributes = null, FlashBagInterface $flashes = null)
    {
?>

https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Htt...

In the sample code above, we can see that SessionStorageInterface is known by the PHP interpreter. So it means that Symfony\Component\HttpFoundation\Session\Storage\SessionStorageInterface is being used. So we can safely write SessionStorageInterface in the doc block instead of the FQCN.

Does it makes any sense ?

It's here not only about documentation for using code in IDE but also on api.drupal.org
If you don't have the full namespace there you are kind of lost, because you have to get to the file, look at the use statements just to figure out what we are talking here about.

I don't agree as the class name is actually a link to the class contained in the file you wants to open. You don't need to look at the use statements as the IDE infers it from the use statement, just like the PHP interpreter do when parsing a file and creates compiler aliases. Moreover, just control + clic on the docblock class name, and it opens the file for you.

Also, you can be kind of lost by all the visual burden that FQCN gives, without speaking of going over the 80-char limit which is a real problem IMO.

RE #99 - that is only a temporary problem. api.drupal.org needs to become namespace-aware, and it should happen pretty soon. See (critical) issue: #1507476: Support namespaces in API module, and comment on that issue if you have ideas about what api.drupal.org needs to do to become "namespace-aware". But at a minimum, item #1 in the "proposed resolution" on that issue is "Class pages, member pages, and class listing pages should show the namespaces the classes belong to.".

RE #98 and #101 - it looks like you are saying that IDEs do not require us to use namespaces in @param, @return, @var, and @see either -- which is the whole reason we adopted the current policy.

Can someone please comment with specific IDEs and whether they are smart enough to infer the correct class if it does not include the namespace? I personally don't use an IDE but comments earlier in this issue said we had to put the namespace in the @tags for the IDEs and now you are saying IDEs don't need them... that's a contradiction.

I know I said in #50 that it was needed and I now contradict myself. I just tested without FQCN in docblock yesterday in eclipse 4.2.1.

When you use 'use' statement, eclipse knows where to find the class and then the FQCN in the docblock is not mandatory.

If you are saying that this current policy was adopted for IDE, then we need a matrix comparison of which IDE infers or not the correct class. I'll update with corresponding results tonight for eclipse and netbeans.

Here we are, feel free to add more editors.

The test has been performed against a fresh install of IDE, with the framework Symfony2. The first column describes the IDE used, the second its version. The Infers FQCN column is a short hand for: Does the IDE infers the fully-qualified class name from the use statements for a class that does not declares its fully-qualified class name (see the screenshot for a more visual definition).

The fact that we put YES in the third column means that we don't need to write the fully-qualified namespace backspaced as the IDE is capable of inferring this from the use definition.

Test method: if on roll-over the IDE displays information about the class doc, then the FQCN is inferred, if not then the test fail. If on control+click the file is opened, the test pass, if not then the test fail.

Updated, can someone here confirms for IntelliJ ?

Is there any other IDE that we can add ?

So for IntelliJ/idea you can either use the classes with it's full absolute namespaces like "\Foo\Bar\Baz" or
anything which would be available in the current code, so "Baz" works if you are in the namespace "Foo\Bar" or has an use entry which adds it.

I think we should not only take care of IDE users, but also the api.drupal.org users/just source code users, which will have a trouble
figuring out where a certain class is stored, if we use relative documentation, as they would have to get to the namespace/uses first and figure out which is is which one.

I basically don't get what the problem is with just documenting it the same way everywhere.

Edit: But TBH what I really don't like is that the standard keeps changing arbitrarily.

api.drupal.org will be taken care of, so don't worry about that. It just isn't yet, but should be soon.

Regarding non-IDE users reading the code, the reason for wanting the fully-qualified namespace in docs in the first place was justified by IDE needs. If IDEs don't need them, I think we should go back to our previous policy, which was to not use namespaces in documentation if the file has them in use/namespace declarations.

If people are following our class naming guidelines, the class names won't be so stupid and ambiguous anyway... See
#1809930: [META] Many core class names violate naming standards

Just for clarity. $namespace\$classname doesn't work, $classname does and \$namespace\$classname does as well.

RE #107... we haven't changed the standard yet. I believe you were the one who asked for the standard that we adopted to change actually, when I tried to add some clarification to what we had already adopted? (see (b) below)...

So... It looks like:
a) We all agree that if we use namespaces, they should start with backslashes. That is in the current standard, so we are OK on that account.

b) Our current standard says "just use namespaces for @tags". But people are asking for more exceptions, such as in the first line of @file blocks and for Overrides/Implements method first lines. That would make the standard very complex.

c) Many people who commented previously on this issue agreed that requiring namespaces everywhere was a lot to ask of people writing documentation and led to a lot of clutter. In fact, we only agreed to requiring namespaces in @param/@return/etc. because people said IDEs required it, which turns out not to be the case.

So... I think we have two reasonable choices here -- and in either case we would keep the requirement in (a) that if we use namespaces, they should start with backslashes, which seems to be OK with IDEs:

1. Always use namespaces for classes in documentation.

2. Never use namespaces for classes in documentation, unless they're completely outside the scope of use/namespace declarations in the file.

I would be happiest with (2) -- requiring the namespaces leads to very very very long lines of documentation and it's a lot of work.... Any other opinions or ideas?

"1. Always use namespaces for classes in documentation."

This is dead-simple to explain to anyone with a text editor and a pulse. It can probably also be automated fairly easily, which means eventually humans not having to care, so we can save our precious human reviewers' brains for problems only humans can spot.

I continue to not understand what great value we gain from not just making this the standard and instead introducing a bunch of "oh, except for"s into our documentation standards that require sophisticated knowledge of PHP namespaces (something our contributor base overall lacks). Beyond level of effort required to introduce the standard the first time and an overall feeling of ickiness about lines of documentation being 96 characters instead of 80 in some places, and I don't find them compelling enough reasons, personally.

RE #111 - I am OK with that idea. if:
- The community agrees.
- We can patch the existing documentation.

As a developer, I really find it very cumbersome to have to repeat the fully qualified namespaces all over again, so I'd vastly prefer option 2) from #110.

This is also the kind of coding/documentation standard that would have a very high chance of not getting followed at all throughout contrib and custom modules, if it involves too much work for no good reason.

And alas, there is no good reason. ;) The only reason would be "consistency", but that implies a tonne of manual/human work in this case, for every single class one might write. D8 will require developers to write a lot of classes, even for the most basic operations.

My very personal stance is already today: I'm only following the current standard for core patches, because I risk patch review complaints otherwise. For my contrib and custom modules, I will definitely not, because the standard only means "work", without anything in return.

NetBeans 7.1 (the current stable) in my experience does not resolve class names in documentation if they're inside a namespace. However, if the 7.2-beta does, then that's good enough for me to consider NetBeans a "with it" program.

Someone should check PHPStorm, too, which I think is the other big PHP IDE these days. (Maybe Komodo?) If their more recent versions cope with docblock class names nicely, then I am fine with shifting to "treat classes in docblocks the same way you do as code, pay attention to your use statements", which is absolutely easier to write.

well, i understood

I very much agree with #111. A simple rule will bring consistency to our documentation.

@jhodgdon I will work on a patch later this week that starts to convert our existing documentation.

#111 summarizes my feelings exactly. Having to assert when I should or shouldn't type the full namespace is maddening, to say nothing of explaining it to someone else.

On the other hand, we don't need to be ridiculously neurotic about this. So:

Always use the fully-qualified namespace in documentation blocks, except in supplementary descriptions where it is clear from context.

Edited to something that you can actually put on a handbook page, with less swearing. ;)

Example:

/**
 * Contains \Drupal\foo\Bar\Class.
 */

namespace Drupal\foo\Bar;

use Drupal\foo\Baz\OtherClass;
use Drupal\foo\Baz\Doodad;

/**
  * Whatevers the whatever from the OtherClass.
  */
Class extends OtherClass {

  /**
   * Overrides \Drupal\foo\Baz\OtherClass:someProperty.
  */
  protected $someProperty;

  /**
   * Does something to the doodad.
   *
   * @param \Drupal\foo\Baz\Doodad
   *   The Doodad object to act on. Saying \Drupal\foo\Baz\Doodad here would be dumb.
   */
  function doodadify() {

  }

}

That way, doxygen can interlink itself, IDEs can always be happy, and text can be text without the tedium of repeating the namespace when it's obvious.

@Lars Toomre:

@jhodgdon I will work on a patch later this week that starts to convert our existing documentation.

No, please don't. This is the sort of massive, disruptive cleanup that should not happen during this particular phase of the release cycle.

Oh. @Crell's suggestion in #114 wouldn't perturb me, if only people understood what it meant. (Edit: And, I guess, apart from the fact that when I'm at line 347 inside file X and I see method Y::whatever() referenced, it's REALLY nice to be able to know that I need to open file a/b/c/Y to look up the method without having to go back up to the top of the file and see what the relevant namespace or use statement is. Maybe this will be less of a problem if the API module is being updated so that classes and methods actually link to the actual thing rather than an incomprehensible list of 200 things wherever the string matches, or something. But for now, it's really helpful, because api.d.o does not yet fully support the D8 codebase.)

I think the root problem is that since virtually no one ever used PHP namespaces before this release cycle (since we didn't require 5.3), people didn't understand what "pay attention to your namespace/use statements" would mean. Because this

namespace Drupal\foo;
/**
 * slkdfjsdlkfjsldjs Drupal\foo\Bar.
 */
class Bar { }

means Drupal\foo\Drupal\foo\Bar, which is probably why @dawehner's IDE breaks on it.

Lars: Not to mention that *we haven't yet agreed upon a new standard* so definitely don't patch this!

So... a few thoughts:

a) I do think everyone agrees that "If you are going to put a namespace in documentation, make it fully-qualified starting with a backslash" is essential. That will get around the problems in #119.

b) I don't like the idea of #117 "use the namespace unless it's clear from context". That leaves too much room for bikeshedding.

c) I personally don't like the idea of #111 "always use the namespace" due to clutter and tedium, and as evidenced by a certain subset of the past 100+ comments, there are other developers that agree with me.

d) It looks like IDEs can deal with not having namespaces. I also think that in most cases, the class name is clear enough within the context of the documentation in a file -- I mean, really, when you're overriding/implementing a method, isn't the context of the class/interface you are overriding/implementing obvious enough?

So I still think "Don't use namespaces in documentation unless they are out of scope of the use/namespace declarations in the file. If you do use a namespace, make sure it's fully-qualified starting with a backslash." would do it...

Re example in #117: Great example @xjm.

Two thoughts before added to handbook page:

a) It should be ' * @param \Drupal\foo\Baz\Doodad $object'.

b) There is confusion about whether there should be or should not be blank lines after a class opening brace and before the class declaration closing brace. The example includes these blank lines. However, some say that such blank lines are not appropriate since they are not part of our coding standards. Others say that they are. Whatever gets included should clarify this issue so that the example can be duplicated whenever this documentation is created or corrected.

Note that #117 is NOT an implementation of #111, despite claiming to be one:

The Doodad object to act on. Saying \Drupal\foo\Baz\Doodad here would be dumb.

That is *exactly* the reason why I am against #111. If you are for *always* using the full namespace you are *against* what is said in the quote. #111 would require using the full namespace in the sentence in the quote.

So what @xjm is proposing is actually precisely the current standard: Use namespaces (directly) after @param, @see, etc., but not in documentation blocks (except where ambigous).

You seem to dislike not having the namespace in the "Contains Foo." that follows the @file declaration. But there really is no difference in principle in the line that follows @param (which is the quote above) and the line that follows @file. So requiring the namespace and one and not in the other by no means increases consistency. Now we could certainly make an *exception* to require the namespace in the line following @file, I have no problem with that. We just need to be clear on what that actually means.

Since I'm already posting, just wanted to say that I am strongly in the camp of not requiring namespaces anywhere (assuming IDEs do not actually need it). I find it a huge PITA personally to constantly have to retype the same thing over and over and it makes patches that rename/move classes just that much larger.

As a developer, I also prefers the option 2 from #110.

Also updated #104 with dawehner comment on IntelliJ.

Symfony 2 have good standards, we can inspire ourselves from their; the code will be consistent.

Anyway the current form: Drupal\foo\Baz\Doodad does not work on my IDE while \Drupal\foo\Baz\Doodad does. So can we take a decision ?

Sylvain/#124: The issue here is whether we should strive to use namespaces in documentation *at all*. We all agree that if we use namespaces, they should start with backslashes.

Related issue: proposed coding standard change when a class extends a class in another name space #2004178: [Policy, no patch] Coding standard should not require "use" when you are extending a class or implementing an interface

This issue hasn't really had any activity since December, and the issue summary says a particular proposal has been adopted, but really the namespaces in documentation page has not been updated with this proposal, and I don't think we've even agreed upon it...

Does anyone think we should figure this out?

I agree with the above and that's why I did this: #2100329: Use \Drupal instead of Drupal to make IDEs and static code analyse tools happy

status update (standard adopted, two issues needed)

This issue is obsolete. The standard now is that all class mentions use namespaces. There was another issue that decided this... not sure where it is but we should close this one.