Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

97 lines (65 sloc) 2.944 kb
p6doc -- an attempt to write something like 'perldoc' for Perl 6
A HTML version of this documenation can be found at http://doc.perl6.org/
With a Rakudo 'perl6' executable in PATH, try
./bin/p6doc Str
to see the documentation for class Str, or
./bin/p6doc Str.split
to see the documentation for method split in class Str
--------
Help Wanted!
Perl 6 is not a small language, and documenting it takes a lot of effort.
Any help is appreciated.
Here are some ways to help us:
* add missing documentation for classes, roles, methods or operators
* add usage examples to existing documentation
* write a tool that renders the documentation as HTML
* proofread and correct the documentation
--------
Some notes:
Q: Why aren't you embedding the docs in the CORE sources?
A: Several reasons:
1. This documentation is intended to be universal with
respect to a given version of the specification,
and not necessarily tied to any specific Perl 6
implementation.
2. Implementations' handling of embedded POD is still
a bit uneven; this avoids potential runtime impacts.
3. A separate repo in the perl6 Github account invites
more potential contributors and editors.
Q: Should I include methods from superclasses or roles
A: No. The HTML version already includes methods from superclasses and
roles, and the p6doc script will be taught about those as well.
Q: Which license is this stuff under?
A: Both code and documentation are available under the Artistic License 2.0
as published by The Perl Foundation. See the 'LICENSE' file for the full
text.
--------
Vision
I want p6doc and doc.perl6.org to become the No. 1 resource to consult
when you want to know something about a Perl 6 type or routine (be it
method, sub or operator). I want it to be useful to every Perl 6 programmer.
-- moritz
--------
Wishlist stuff:
* Search terms like ".any", "any()", "&any", "::Any", etc. can be
used to disambiguate whether information is sought on a method,
subroutine, type, etc.
* Searching for "Int.Bool" returns the documentation for the
inherited method "Numeric.Bool".
* Searching for an operator name returns the documentation for
the operator. ("p6doc '%%'" returns the documentation for
&infix:<%%>.)
* Perl6 implementations could embed P<...> tags in their source
code that would then inline the corresponding entry from p6doc.
This would enable things like "&say.WHY" to (dynamically!)
retrieve the documentation string from p6doc, without having
to duplicate the documentation in the CORE.setting sources
or to encode the documentation into the binaries.
Example:
# In Rakudo's src/core/IO.pm:
#= P<p6doc/&print>
sub print(|$) { ... }
#= P<p6doc/&say>
sub say(|$) { ... }
#= P<p6doc/&note>
sub note(|$) { ... }
Jump to Line
Something went wrong with that request. Please try again.