How to documenting variables included from other files?

[Paul M. Jones]

Hi all,

In Aura v2, we're using a 2-stage config system. As part of this system, we inject a $di variable into include files in a limited scope. This means that config files can expect to have a $di variable present, even though it has not been defined in the config file itself. It's the equivalent of including another file that has already defined $di.

Until now I have been documenting that in the config file using @var, but I realize now that @var is for variables defined in the file itself, not for variables that are expected to be present already.

What do we think would be a more appropriate way of documenting the expected presence of a variable that is not defined in the file being documented?


--
Paul M. Jones
pmjo...@gmail.com
http://paul-m-jones.com

[Mike van Riel]

Hi Paul,

This is actually a rather good question without a good answer. In the past phpDocumentor 1 has used the @global tag ( http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.global.pkg.html) to describe a global variable's declaration and usage; though the second usage of @global is restricted to functions (and by extension methods).

So: that won't help you in this situation.

It has become more or less normal to use @var for this purpose but @var is originally meant to be used for properties only ( http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/var.html), hence the name. But for the time being I think this is the best supported way out there.

With PSR-5 we intend to introduce a new tag, tentatively called @type currently, that will allow you to declare the type of a variable (independent of prior usage or whether this is the declaration) and provide an extended description. Unfortunately this is still under discussion, it might be that this tag receives a different name or that @var is repurposed to fulfill this duty. Though the latter does not have my preference as it is not a semantic tag.

Does that more or less answer your question?

Kind regards,

Mike van Riel

[Paul M. Jones]

To sum up:

- @global is definitely not it;
- keep using @var as the best of the available choices;
- later, convert appropriate @var tags to @type (tbd);
- remaining @var tags will then be more suitably descriptive.

Sounds fine to me, Mike; thanks!

In the mean time, I suggest that the @var tags of the type I'm talking about (i.e., variables defined elsewhere that are expected to be present) should be valid in the file-level docblock. Then they're not attached to any particular variable declaration within the file itself.

[Mike van Riel]

On 12/11/2013 06:55 PM, Paul M. Jones wrote:
> On Dec 11, 2013, at 11:44 AM, Mike van Riel <draco...@gmail.com> wrote:
>
>> On 12/11/2013 06:15 PM, Paul M. Jones wrote:
>>> Hi all,
>>>
>>> In Aura v2, we're using a 2-stage config system. As part of this system, we inject a $di variable into include files in a limited scope. This means that config files can expect to have a $di variable present, even though it has not been defined in the config file itself. It's the equivalent of including another file that has already defined $di.
>>>
>>> Until now I have been documenting that in the config file using @var, but I realize now that @var is for variables defined in the file itself, not for variables that are expected to be present already.
>>>
>>> What do we think would be a more appropriate way of documenting the expected presence of a variable that is not defined in the file being documented?
>>>
>>>
>>>
>> Hi Paul,
>>
>> This is actually a rather good question without a good answer. In the past phpDocumentor 1 has used the @global tag ( http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.global.pkg.html) to describe a global variable's declaration and usage; though the second usage of @global is restricted to functions (and by extension methods).
>>
>> So: that won't help you in this situation.
>>
>> It has become more or less normal to use @var for this purpose but @var is originally meant to be used for properties only ( http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/var.html), hence the name. But for the time being I think this is the best supported way out there.
>>
>> With PSR-5 we intend to introduce a new tag, tentatively called @type currently, that will allow you to declare the type of a variable (independent of prior usage or whether this is the declaration) and provide an extended description. Unfortunately this is still under discussion, it might be that this tag receives a different name or that @var is repurposed to fulfill this duty. Though the latter does not have my preference as it is not a semantic tag.
>>
>> Does that more or less answer your question?
> To sum up:
>
> - @global is definitely not it;
> - keep using @var as the best of the available choices;
> - later, convert appropriate @var tags to @type (tbd);
> - remaining @var tags will then be more suitably descriptive.

That is basically it yes, though if it is up to me then the new tag will
supercede the @var and thus deprecate it. @var has no purpose once the
new tag is in place :)

> In the mean time, I suggest that the @var tags of the type I'm talking about (i.e., variables defined elsewhere that are expected to be present) should be valid in the file-level docblock. Then they're not attached to any particular variable declaration within the file itself.

It is something I have considered but I am in doubt whether that is a
good thing, the downsides that I see are:

* because usage and declaration can be many lines of code separate from
eachother it might happen that people forget to remove the tag from the
DocBlock when they refactor away the variable
* If a variable is re-used (which is bad practice but happens ;)) it
might become unclear which definition it is
* Sometimes you want to document a variable with a foreach loop; and
that has scope local to that foreach

So, I don't know yet .. it would also make it harder for parsers but
that is a secondary thing :)

[Gareth Pursehouse]

hey so was this ever solved?

In attempt to declare that a variable exists inside an included file.

@var $variable \ClassNamespace\Class

isn't working... It does allow -> to autocomplete after the full variable name is typed out. But the IDE (eclipse in my case) isn't aware of the variable existing on its own