Feature Proposal: Don't Ship *.pm Documentation Topics

Motivation

Discourage use of undocumented functions.

Description and Documentation

As of TWiki 4.1, TWiki ships with 55 *.pm documentation topics, from TWikiAccessControlExceptionDotPm through TWikiUsersTWikiUserMappingDotPm. This looks like an invitation for casual users to use internal TWiki functions. For example, see WhereFindNoticeOfApiChanges.

On the other hand, developers are encouraged to use an SVN checkout to work on TWiki and TWiki extensions. Even though more useful for developers, the SVN checkout does not have the *.pm documentation topics.

Proposal:

• Remove all *.pm documentation topics from the distribution except the ones we officially promote, namely
  • TWikiFuncDotPm
  • TWikiMetaDotPm
  • TWiki::OopsException
  • TWiki::AccessControlException
  • TWiki::Attrs
  • (Anything else?)

Open question:

• Can we do anything to make *.pm documentation more accessible to core developers?

Impact

-- Contributors: PeterThoeny - 20 May 2007

Discussion

yes, i agree that we shouldn't ship those files.

more accessible to core developers? if they want to see that doc within twiki, then they can install PerlDocPlugin or use perldoc TWiki::Module

-- WillNorris - 20 May 2007

I agree. We need to document the exceptions (TWiki::OopsException and TWiki::AccessControlException) and TWiki::Attrs (utility class) as well.

As for making the pm doc more accessible to developers, can't we use the PerlDocPlugin? I thought that was what it was for....

Arguably we need to add

• TWiki::InfixParser
• TWiki::ListIterator
• TWiki::LineIterator
• TWiki::Time

-- CrawfordCurrie - 20 May 2007

To make it really clear what is official API, would it make sense to rename TWiki::OopsException to TWiki::Func::OopsException? (same with all other official modules.)

-- PeterThoeny - 20 May 2007

Hmmm. That's a tough one. While I agree with the principle of grouping public packages, 'Func' has a loaded meaning to me; it means "here's a functional API that you can use if you can't get your head round object orientation". As such naming objects into that package hierarchy is just confusing.

A better approach would be to use a more intention-revealing name; for example TWiki::Public. Shame Func missed the boat, it would have been TWiki::Public::Func.

However I suspect we are too late for any of these renames. OopsException and AccessControlException are already being used by some extensions. it would be easier to rename the Core classes to distinguish them from the public interface e.g.

TWiki::Core::Users
TWiki::Core::LoginManager
TWiki::Core::Plugin

-- CrawfordCurrie - 21 May 2007

As for making the docs more available to developers, developers can use tools/gendocs.pl to create the doc topics and put them in the TWiki web.

+1 to the renaming of the Core modules.

-- RafaelAlvarez - 21 May 2007

It is definitely too late to rename TWiki::Func.

To remain compatible, is there a way to have one and the same module exposed as TWiki::OopsException and TWiki::Public::OopsException?

-- PeterThoeny - 21 May 2007

Will says there is; but I think it's the wrong way to go. i would far rather rename the unpublished modules, and leave the published ones (such as TWiki::Func and TWiki::OopsException) untouched.

-- CrawfordCurrie - 21 May 2007

It looks like we have an agreement to not ship TWiki's internal Perl module docs with the TWiki package. I filed Bugs:Item4177 to track this item.

-- PeterThoeny - 01 Jun 2007