Skip to content
This repository
tree: bb467ff475
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 97 lines (65 sloc) 2.944 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
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(|$) { ... }


Something went wrong with that request. Please try again.