Feature Proposal: Add package navigation to Perl Doc
Motivation
Make it easier to access documentation.
Description and Documentation
Make it possible to browse through all the Perl Doc pages by package hierarchy:
- Links to "children" packages, with a brief summary of each child package
- Show "parent" packages by creating a new title on top of PerlDoc that has links to each "prefix" package
- The above is accomplished via %DOC_TITLE% and %DOC_CHILDREN% injected into PerlDoc in the same way as %SMELLS%.
Generate the summary of each child package by using the first few lines under ---++ package XXX in the pod. Find the first line that contains only whitespace, and truncate from there onwards.
Create a new topic called System.PublishedAPI that defines the API intended for end-users:
- Add a checkbox labelled "Public" to PerlDoc that determines if all sub-packages are shown, or only published ones.
- If the currently displayed package is in System.PublishedAPI, prefix it with "public" else with "internal".
Other odds and ends:
- If the public checkbox is clicked then methods that start with _ are suppressed.
- If PerlDoc is viewed with no package selected, render "Foswiki" by default.
See also a
big picture of what packages currently link to each other (seeded with published packages).
Examples
This is currently checked into trunk and can be seen at
http://trunk.foswiki.org/System/PerlDoc (much apologies for checking in code for a non
AcceptedProposal, I had a misunderstanding).
The same code can be seen on my website:
http://kiplubliner.com/view/System/PerlDoc
Impact
Implementation
Tasks.Item11437
--
Contributors: KipLubliner - 08 Jan 2012
Discussion
(Cleaned up description & comments; previous content can be seen at r16)
Open Issues:
- Some of the package descriptions don't look very good. E.g. the descriptions for Foswiki::*Iterator packages all simply tell us their parent class. But this information is available anyway (there already is code checked into trunk for scanning @ISA). I would be glad to help to clean up package descriptions, but I don't want to interfere with other development.
- Child packages are hidden behind a twisty. For a package like Foswiki with many children packages, this means that this is basically a 'modal' interface - the user has to decide to browse the class (Twisty is closed), or navigate the hierarchy (Twisty is open). I think that it would be nicer to use a "sidebar" to render the children (somewhat like javadoc).
- Should
$VERSION
and $RELEASE
be rendered in package description? This seems specific only to Plugins / Contribs and the info is available elsewhere anyway.
- Per comment from CrawfordCurrie, Meta is going to change after release of Store2. Is it desirable to document that an API is going to become deprecated but is not currently?
This picture is going to change again soon. The ongoing work on Store2 is going to remove Meta in its current form. I've been reluctant to "publish" Form because the API is a bit s**t and needs work before being cast in stone (not least to allow other implementations of Form to exist). Prefs should only be access through Func. UI classes should not be published, nor should the cache. I removed Extensions from your list.
-- CrawfordCurrie - 12 Jan 2012
--
KipLubliner - 14 Jan 2012
Note that the bug item should be included in the "BugTracking" field of this topic for reference.
You broke the unit tests. I will fix them.
--
CrawfordCurrie - 15 Jan 2012
Thanks for your help! I have yet to learn how to run the unit tests locally. Also, I checked in a fix to your fix (so that viewing
PerlDoc without any parameters will display Foswiki package, and not ::).
--
KipLubliner - 15 Jan 2012
The "public only" checkbox does not work on 1.1.5 beta 1 because this topic does not exist:
http://foswiki.org/System/PublishedAPI
This is the version of the file in trunk:
http://trunk.foswiki.org/System/PublishedAPI
--
KipLubliner - 08 Mar 2012
GeorgeClark helped me update the manifest file for 1.1.5.
--
KipLubliner - 08 Mar 2012
Packages that should be in
PublishedAPI. If any should be removed, please add a comment:
so 'released in' 1.2.0 means that we still have the opportunity to not release them and provide a narrower API via Foswiki::Func?
--
SvenDowideit - 14 Mar 2012
Updated version of
PublishedAPI - for trunk. For 1.1 branch, I will remove references to packages that CC marked as 1.2.0.
--
KipLubliner - 17 Mar 2012
Hm. Aren't the following also "public" in that anyone implementing a custom Login or Mapping manager is required to override / implement their methods? My assumption would be that anything in confgure that is dynamically detected / presented as a choice, like the Password, Login and Mapping managers would need to be part of the public API. Probably the Logging manager as well, as we've wanted to encourage someone to write a more advanced logger.
Need footnotes however that these are not for use by Plugins, but are for the exclusive use of pluggable features.
--
GeorgeClark - 17 Mar 2012
George, I integrated your updates.
--
KipLubliner - 18 Mar 2012
Interface for Plugin, Contrib and Skin Developers
See
DevelopingPlugins for more information.
Interface for Advanced Integration
See
UserAuthentication for more information.
--
KipLubliner - 20 Mar 2012