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. In time we'll develop a mechanism to extract those automatically. Including all inherited methods manually simply doesn't scale. 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. -------- 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/¬e> sub note(|$) { ... }