-
Notifications
You must be signed in to change notification settings - Fork 293
/
README
88 lines (60 loc) · 2.63 KB
/
README
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
p6doc -- an attempt to write something like 'perldoc' for Perl 6
So far only documentation for complete modules or classes is supported.
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(|$) { ... }