thekid/rfc — Issue #105: RFC 0105: Package-Info
Author: thekid
Created: 2011-10-09 15:07:41+00:00
State: open
Labels: rfc

Scope of Change
====
For the apidoc generator to embed documentation about a package (e.g.,
lang, lang.reflect, webservices.json, ...) special package-info files
will be added to skeleton.

Rationale
====
Complete documentation.

Functionality
====
The file will be called "package-info.xp" and thus resembles the convention
used in JavaDoc >= 1.5.0.

Example:

```php
newInstance();
*
* Invoking a method by its name:
* $c= XPClass::forName('util.Binford');
* $c->getMethod('setPoweredBy')->invoke($c->newInstance(), array(6100));
*
* Retrieving annotations:
* $s= $service->getClass()->getMethod($invoked)->getAnnotation('security');
* if (!in_array($role, $s['roles'])) {
* throw new IllegalAccessException('Access denied to '.$invoked);
* }
*
* @see xp://lang.XPClass
* @purpose Reflection
*/
package lang.reflect {
}
?>
```

Security considerations
====
n/a

Speed impact
====
n/a

Dependencies
====
n/a

Related documents
====
- http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#packagecomment
Package Comment Files

- http://xp-framework.net/rfc/contrib/rfc0105.diff
Diff for text.doclet which supports package-info.xp parsing

- http://xp-framework.net/rfc/contrib/rfc0105-new-apidoc-screenshot.png
Screenshot of how the new apidocs might look like when viewing packages

Comments
====
- friebe, Wed Jan 3 16:25:57 CET 2007
Because the file actually does not contain valid PHP sourcecode, I'd
prefer to call the file "package-info.xp"...

- friebe, Sat Jan 6 17:06:35 2007
Added package-info.xp files to the lang package and its subpackages,
lang.reflect, lang.archive and lang.types.
Other packages will be done while we're going:)