Bug 435070 – eclassdoc: @tag for eclass-exported variables

• Status: CONFIRMED
• Product: Gentoo Linux

[Description Michał Górny 2012-09-14 20:20:57 UTC]

The current eclassdoc syntax permits only documenting variables which are supposed to be set by user. It would be useful to have a tag like @EXPORTED which would tell the user that a particular variable is actually created and exported by the eclass for ebuild to use.

[Comment 1 SpanKY 2012-09-17 03:06:53 UTC]

i don't think your interpretation of @VARIABLE or @ECLASS-VARIABLE is correct.  there is no "these are only for vars for people to set".  there is only "this is a variable the eclass uses".  whether it's an "input" or "output" or maybe even both is based on the description.

i don't see what adding a new tag would even gain here.

[Comment 2 Michał Górny 2012-09-17 07:53:19 UTC]

I just meant a tag instead of @DEFAULT_UNSET and so on.

[Comment 3 SpanKY 2012-09-19 05:47:04 UTC]

so you don't have a default value and want to avoid the warnings emitted by the conversion script ?

[Comment 4 Michał Górny 2012-09-19 08:26:56 UTC]

(In reply to comment #3)
> so you don't have a default value and want to avoid the warnings emitted by
> the conversion script ?

The point is that the 'default' value is calculated a bit complex. I think I will just put a default like FOO="bar1 bar2 ..." (with the ellipsis).

But I think we should be explicitly allowed to specify that kind of variable, even if it will have no clear visual consequences now.

[Comment 5 SpanKY 2013-01-22 07:36:34 UTC]

(In reply to comment #4)

you've lost me.  the original request was for "@EXPORTED" so as to differentiate between user variables (i.e. set in make.conf or equiv) and developer variables (i.e. set in ebuilds/eclasses).

after that, you started talking about detecting default values.

these issues are orthogonal, so what is it you're really after ?

[Comment 6 Michał Górny 2013-01-22 14:17:16 UTC]

(In reply to comment #5)
> (In reply to comment #4)
> 
> you've lost me.  the original request was for "@EXPORTED" so as to
> differentiate between user variables (i.e. set in make.conf or equiv) and
> developer variables (i.e. set in ebuilds/eclasses).
> 
> after that, you started talking about detecting default values.
> 
> these issues are orthogonal, so what is it you're really after ?

No. The original request was for "@EXPORTED" as variable *set by eclass* (not set by ebuild, read by ebuild) vs variables set by eclass or ebuild.

For example, PYTHON_USEDEP in python-r1. It is set by the eclass to be used in the ebuild but ebuild is not supposed to *ever* set it.