rfc @access, @api, @private...

[David Buchmann]

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

hi,

i am building a documentation for the jackalope library with docblox and
we are using @api and @private to annotate which public methods are
really part of the api and which are implementation specific.
i would like to build support to reflect that information in docblox.
mike said something about @access support as well. i would go like this:

in the structure.xml, we create the tag "access" with a type (usually
public or private) and optionally a description.
the access value is used in the default view to use a
visibility_public_privateaccess / publicaccess icon. (btw: this should
all be done with css, then it would be much easier to customize the look
and feel)
additionally, there is the textual information in the details of the method.

to support other tags, the parser maps them into access with type
public/private. i see:

@private, @internal => @access private
@api => @access public

are there other conventions that should be supported?

cheers,david
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk5p1moACgkQqBnXnqWBgIvuCACgorZNxjFLLbV85CzBT1s5tKwX
qfUAoIdun0yETDroeDGgesl5C0AOBRt1
=NL3b
-----END PGP SIGNATURE-----

[Mike van Riel]

Hello David,

Your description sounds a lot like something with which the `visibility`
argument and @internal tag in DocBlox can already help.

In contrary to phpDocumentor (which hid private by default unless
--parseprivate was specified) does DocBlox show all visibility
specifiers unless you use the --visibility argument.

This argument allows a comma-separated list of allowed visibility
specifiers. For example: `--visibility public,protected` to show only
public and private members.

Perhaps we can expand on this by allowing an expression instead of a
comma-separated list with which you can tune this (and thus adding to
@api the list of visibility specifiers).

Concerning @private; the phpDoc standard already has @internal to
indicate that that element should not be visible by default (only when
--parseprivate is provided) which essentially makes it private if I
understand you correctly.

Regards,

Mike