[gentoo-dev] updated elass documentation syntax

[gentoo-dev] updated elass documentation syntax

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 741 bytes --]

ive extended the eclass documentation format a little for variables.  you can 
now use the markers:

	@DEFAULT_UNSET
avoid overhead of adding useless constructs like:
	: ${FOO:=}
this way the awk script wont warn when it was unable to find a default value 
for the variable in question

	@REQUIRED
similar to the previous construct; this allows people to mark a variable so 
that ebuild writers know they must provide for this.  in the man page output, 
the variable will be marked with "(REQUIRED)".

	@INTERNAL
some people like to document all variables, even ones that ebuilds/users 
shouldnt be setting (i.e. internal state variables).  now you can do just that 
and the variable wont be included in the output.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] updated elass documentation syntax

[Tomáš Chvátal]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Dne 21.8.2010 21:27, Mike Frysinger napsal(a):
> ive extended the eclass documentation format a little for variables.  you can 
> now use the markers:
> 
> 	@DEFAULT_UNSET
> avoid overhead of adding useless constructs like:
> 	: ${FOO:=}
> this way the awk script wont warn when it was unable to find a default value 
> for the variable in question
> 
> 	@REQUIRED
> similar to the previous construct; this allows people to mark a variable so 
> that ebuild writers know they must provide for this.  in the man page output, 
> the variable will be marked with "(REQUIRED)".
> 
> 	@INTERNAL
> some people like to document all variables, even ones that ebuilds/users 
> shouldnt be setting (i.e. internal state variables).  now you can do just that 
> and the variable wont be included in the output.
> -mike
Mike,
if i define variable in some function it gets into functions section for
manpage. Not sure if that is your area to fix too :)

Cheers

Tom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkxwKQkACgkQHB6c3gNBRYfIzQCgvDG7fM+LBA0wjtkubzmS8K54
vPwAoL49i9HPst2uTLqBTsHPcWYEFpql
=5jB0
-----END PGP SIGNATURE-----

Re: [gentoo-dev] updated elass documentation syntax

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 323 bytes --]

On Saturday, August 21, 2010 15:29:13 Tomáš Chvátal wrote:
> if i define variable in some function it gets into functions section for
> manpage. Not sure if that is your area to fix too :)

please illustrate with an example.  or just point me to the eclass and 
highlight the problem with the man page output.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] updated elass documentation syntax

[Tomáš Chvátal]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Dne 21.8.2010 21:38, Mike Frysinger napsal(a):
> On Saturday, August 21, 2010 15:29:13 Tomáš Chvátal wrote:
>> if i define variable in some function it gets into functions section for
>> manpage. Not sure if that is your area to fix too :)
> 
> please illustrate with an example.  or just point me to the eclass and 
> highlight the problem with the man page output.
> -mike
xorg-2.eclass
variable: CONFIGURE_OPTIONS.

Tom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkxwLGMACgkQHB6c3gNBRYd8hQCfTGTqCCCI7baPfawvY2JM93y1
HJQAn1orirFKsaV3YJcb4LT5M8RXRj+0
=CY28
-----END PGP SIGNATURE-----

Re: [gentoo-dev] updated elass documentation syntax

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 772 bytes --]

On Saturday, August 21, 2010 15:43:31 Tomáš Chvátal wrote:
> Dne 21.8.2010 21:38, Mike Frysinger napsal(a):
> > On Saturday, August 21, 2010 15:29:13 Tomáš Chvátal wrote:
> >> if i define variable in some function it gets into functions section for
> >> manpage. Not sure if that is your area to fix too :)
> > 
> > please illustrate with an example.  or just point me to the eclass and
> > highlight the problem with the man page output.
> 
> xorg-2.eclass
> variable: CONFIGURE_OPTIONS.

function-specific variables are intended to be interwoven with the function 
they're specific to.  that's the difference between @ECLASS-VARIABLE and 
@VARIABLE.

i guess the display could be clarified to mention which function they're tied 
to exactly ...
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] updated elass documentation syntax

[Tomáš Chvátal]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Dne 21.8.2010 22:32, Mike Frysinger napsal(a):
> On Saturday, August 21, 2010 15:43:31 Tomáš Chvátal wrote:
>> Dne 21.8.2010 21:38, Mike Frysinger napsal(a):
>>> On Saturday, August 21, 2010 15:29:13 Tomáš Chvátal wrote:
>>>> if i define variable in some function it gets into functions section for
>>>> manpage. Not sure if that is your area to fix too :)
>>>
>>> please illustrate with an example.  or just point me to the eclass and
>>> highlight the problem with the man page output.
>>
>> xorg-2.eclass
>> variable: CONFIGURE_OPTIONS.
> 
> function-specific variables are intended to be interwoven with the function 
> they're specific to.  that's the difference between @ECLASS-VARIABLE and 
> @VARIABLE.
> 
> i guess the display could be clarified to mention which function they're tied 
> to exactly ...
> -mike
Yep some clarification there would help :)
Btw is there somewhere complete eclassdoc specs document?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkxw2b0ACgkQHB6c3gNBRYc54ACgyeAF6jG8pwFerAlW6t7yii5b
ZuAAn3b+rPrEF8gQVJGImzP3eQOEn7ce
=rt7x
-----END PGP SIGNATURE-----

Re: [gentoo-dev] updated elass documentation syntax

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 152 bytes --]

On Sunday, August 22, 2010 04:03:09 Tomáš Chvátal wrote:
> Btw is there somewhere complete eclassdoc specs document?

in the awk file itself
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]