Item9235: Oops: Revert "Revert "Item9232: more doccing""

This reverts commit 83a56069380b7a3e2fa55da873dcdc0c3943edaf.

git-svn-id: http://svn.foswiki.org/trunk@8027 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

core/bin/configure

@@ -31,8 +31,9 @@ The Model consists of a simple node tree, where each node represents a
 structural element in the *presentation* of the configuration (this may
 not be consistent with the structure of $Foswiki:cfg, so beware). Each
 leaf node has an associated Type (in the Types subdirectory) that has
-collected model and view behaviours for the basic types. The node tree
-is made up of the classes:
+collected model and view behaviours for the basic types.
+
+Class hierarchy
   * Foswiki::Configure::Item
      * Foswiki::Configure::Value - a leaf value
      * Foswiki::Configure::Section - a running node
@@ -59,8 +60,15 @@ the CGI configuration. Several of the bespoke UIs (CGISetup, Introduction,
 Welcome) have corresponding Checkers, which act as placeholders in the
 model for these sections.
 
-These are top-level pluggable UI components. All the main screens are
-implemented as UIs, under Foswiki::Configure::UIs.
+Class hierarchy
+   * Foswiki::Configure::UI
+      * Foswiki::Configure::Checker
+         * Foswiki::Configure::Checkers::* - see below
+      * Foswiki::Configure::UIs::* - components used in building screens
+         * Foswiki::Configure::UIs::Item
+            * Foswiki::Configure::UIs::Section
+               * Foswiki::Configure::UIs::Root
+            * Foswiki::Configure::UIs::Value
 
 ---+++ Checkers
 Checkers give checking and guessing support for configuration values. Checkers
@@ -71,12 +79,34 @@ environment sanity (BasicSanity)
 
 ---+++ Types
 Types provide some UI support in the form of type-specific prompters.
-this is really an abuse of the Model, but it saves creating
+This is really an abuse of the Model, but it saves creating
 decorator classes for all the Model types.
 
 HTML is generated for the model using Visitor pattern. Each node in the tree
 is visited in depth-first order.
 
+Class hierarchy
+   * Foswiki::Configure::Type - base
+      * Foswiki::Configure::Types::NUMBER - numerical type (perl float values)
+         * Foswiki::Configure::Types::OCTAL - octal (permissions)
+      * Foswiki::Configure::Types::BOOLEAN - boolean type
+         * Foswiki::Configure::Types::LANGUAGE
+      * Foswiki::Configure::Types::PERL - perl structure
+      * Foswiki::Configure::Types::SELECT - select from a list of values
+         * Foswiki::Configure::Types::SELECTCLASS - select a class from a path
+      * Foswiki::Configure::Types::STRING - string type
+         * Foswiki::Configure::Types::REGEX - regular expression
+         * Foswiki::Configure::Types::COMMAND - shell command
+         * Foswiki::Configure::Types::PASSWORD - hidden password
+         * Foswiki::Configure::Types::PATH - file path (/)
+         * Foswiki::Configure::Types::URL - absolute url path (/)
+         * Foswiki::Configure::Types::URLPATH - relative url path (/)
+      * Foswiki::Configure::Types::UNKNOWN - unknown type
+
+TODO:
+The type classes are the obvious place to attach client-side javascript
+validators, thus releasing the server-side checkers to consider the "deeper"
+issues.
 
 =cut
 

core/lib/Foswiki/Configure/Checker.pm

@@ -1,5 +1,15 @@
 # See bottom of file for license and copyright information
 
+=begin TML
+
+---+ package Foswiki::Configure::Checker;
+
+Base class of all checkers. Checkers give checking and guessing support
+for configuration values. Most of the methods of this class are intended
+to be protected i.e. only available to subclasses.
+
+=cut
+
 package Foswiki::Configure::Checker;
 
 use strict;
@@ -13,16 +23,14 @@ use CGI        ();
 
 =begin TML
 
----+++ ObjectMethod check($value) -> $html
+---++ ObjectMethod check($value) -> $html
    * $value - Value object for the thing being checked
 
 Entry point for the value check. Overridden by subclasses.
 
-Returns html formatted by $this->ERROR(), WARN(), NOTE(), guessed() or
-hand made _OR_ and empty string to be inserted in the configure UI
-
-The checker can either check the sanity of the previously saved value,
-or guess a one if none exists:
+Returns html formatted by $this->ERROR(), WARN(), NOTE(), or
+hand made _OR_ an empty string. The output of a checker will normally
+be included in an HTML table, so don't get too carried away.
 
 =cut
 
@@ -33,6 +41,16 @@ sub check {
     return '';
 }
 
+=begin TML
+
+---++ PROTECTED ObjectMethod guessed($status) -> $html
+
+A checker can either check the sanity of the previously saved value,
+or guess a one if none exists. If the checker guesses, it should call
+=$this->guessed(0)= (passing 1 if the guess was an error).
+
+=cut
+
 sub guessed {
     my ( $this, $error ) = @_;
 
@@ -50,6 +68,15 @@ HERE
     }
 }
 
+=begin TML
+
+---++ PROTECTED ObjectMethod warnAboutWindowsBackSlashes($path) -> $html
+
+Generate a warning if the supplied pathname includes windows-style
+path separators.
+
+=cut
+
 sub warnAboutWindowsBackSlashes {
     my ( $this, $path ) = @_;
     if ( $path =~ /\\/ ) {
@@ -60,6 +87,15 @@ sub warnAboutWindowsBackSlashes {
     }
 }
 
+=begin TML
+
+---++ PROTECTED ObjectMethod guessMajorDir($cfg, $dir, $silent) -> $html
+
+Try and guess the path of one of the major directories, by looking relative
+to the absolute pathname of the dir where configure is being run.
+
+=cut
+
 sub guessMajorDir {
     my ( $this, $cfg, $dir, $silent ) = @_;
     my $msg = '';
@@ -79,10 +115,10 @@ sub guessMajorDir {
 }
 
 =begin TML
----+++ ObjectMethod checkTreePerms($path, $perms, $filter) -> 'html'
 
-Called by a Checker to perform
-a recursive check of the specified path.  The recursive check 
+---++ PROTECTED ObjectMethod checkTreePerms($path, $perms, $filter) -> $html
+
+Perform a recursive check of the specified path.  The recursive check 
 is limited to the configured "PathCheckLimit".  This prevents excessive
 delay on installations with large data or pub directories.  The
 count of files checked is available in the class method $this->{fileCount}
@@ -208,6 +244,18 @@ sub checkTreePerms {
     return $permErrs . $errs;
 }
 
+=begin TML
+
+---++ PROTECTED ObjectMethod checkCanCreateFile($path) -> $html
+
+Check that the given path can be created (or, if it already exists,
+can be written). If the existing path is a directory, recursively
+check for rw permissions using =checkTreePerms=.
+
+Returns a message or the empty string if the check passed.
+
+=cut
+
 sub checkCanCreateFile {
     my ( $this, $name ) = @_;
 
@@ -240,11 +288,20 @@ sub checkCanCreateFile {
     return '';
 }
 
-# Since Windows (without Cygwin) makes it hard to capture stderr
-# ('2>&1' works only on Win2000 or higher), and Windows will usually have
-# GNU tools in any case (installed for Foswiki since there's no built-in
-# diff, grep, patch, etc), we only check for these tools on Unix/Linux
-# and Cygwin.
+=begin TML
+
+---++ PROTECTED ObjectMethod checkGnuProgram($prog) -> $html
+
+Check for the availability of a GNU program.
+
+Since Windows (without Cygwin) makes it hard to capture stderr
+('2>&1' works only on Win2000 or higher), and Windows will usually have
+GNU tools in any case (installed for Foswiki since there's no built-in
+diff, grep, patch, etc), we only check for these tools on Unix/Linux
+and Cygwin.
+
+=cut
+
 sub checkGnuProgram {
     my ( $this, $prog ) = @_;
     my $mess = '';
@@ -284,7 +341,14 @@ sub checkGnuProgram {
     return $mess;
 }
 
-# Check for a compilable RE
+=begin TML
+
+---++ PROTECTED ObjectMethod checkRE($keys) -> $html
+Check that the configuration item identified by the given keys represents
+a compilable perl regular expression.
+
+=cut
+
 sub checkRE {
     my ( $this, $keys ) = @_;
     my $str;
@@ -300,38 +364,15 @@ MESS
     return '';
 }
 
-sub copytree {
-    my ( $this, $from, $to ) = @_;
-    my $e = '';
-
-    if ( -d $from ) {
-        if ( !-e $to ) {
-            mkdir($to) || return "Failed to mkdir $to: $!<br />";
-        }
-        elsif ( !-d $to ) {
-            return "Existing $to is in the way<br />";
-        }
+my $rcsverRequired = 5.7;
 
-        my $d;
-        return "Failed to copy $from: $!<br />" unless opendir( $d, $from );
-        foreach my $f ( grep { !/^\./ } readdir $d ) {
-            $f =~ /(.*)/;
-            $f = $1;    # untaint
-            $e .= $this->copytree( "$from/$f", "$to/$f" );
-        }
-        closedir($d);
-    }
+=begin TML
 
-    if ( !$e && !-e $to ) {
-        require File::Copy;
-        if ( !File::Copy::copy( $from, $to ) ) {
-            $e = "Failed to copy $from to $to: $!<br />";
-        }
-    }
-    return $e;
-}
+---++ PROTECTED ObjectMethod checkRCSProgram($prog) -> $html
+Specific to RCS, this method checks that the given program is available.
+Check is only activated when the selected store implementation is RcsWrap.
 
-my $rcsverRequired = 5.7;
+=cut
 
 sub checkRCSProgram {
     my ( $this, $key ) = @_;

core/lib/Foswiki/Configure/Checkers/Store/Implementation.pm

@@ -18,27 +18,6 @@ sub check {
 RcsWrap does not work well on Windows, please use RcsLite.
 EOF
     }
-
-    if ( $Foswiki::cfg{Store}{Implementation} =~ /RcsWrap/ ) {
-
-        # Check that GNU diff is found in PATH; used by rcsdiff
-        $mess .= $this->checkGnuProgram('diff');
-
-        # Check all the RCS programs
-        $mess .= $this->checkRCSProgram('initBinaryCmd');
-        $mess .= $this->checkRCSProgram('initTextCmd');
-        $mess .= $this->checkRCSProgram('tmpBinaryCmd');
-        $mess .= $this->checkRCSProgram('ciCmd');
-        $mess .= $this->checkRCSProgram('ciDateCmd');
-        $mess .= $this->checkRCSProgram('coCmd');
-        $mess .= $this->checkRCSProgram('histCmd');
-        $mess .= $this->checkRCSProgram('infoCmd');
-        $mess .= $this->checkRCSProgram('histCmd');
-        $mess .= $this->checkRCSProgram('diffCmd');
-        $mess .= $this->checkRCSProgram('lockCmd');
-        $mess .= $this->checkRCSProgram('unlockCmd');
-        $mess .= $this->checkRCSProgram('delRevCmd');
-    }
 
     return $mess;
 }

core/lib/Foswiki/Configure/Types/URL.pm

@@ -5,8 +5,8 @@ package Foswiki::Configure::Types::URL;
 use strict;
 use warnings;
 
-use Foswiki::Configure::Type ();
-our @ISA = ('Foswiki::Configure::Type');
+use Foswiki::Configure::Types::STRING ();
+our @ISA = ('Foswiki::Configure::Types::STRING');
 
 sub new {
     my $class = shift;

core/lib/Foswiki/Configure/Types/URLPATH.pm

@@ -8,6 +8,12 @@ use warnings;
 use Foswiki::Configure::Types::STRING ();
 our @ISA = ('Foswiki::Configure::Types::STRING');
 
+sub new {
+    my $class = shift;
+
+    return bless( { name => 'URLPATH' }, $class );
+}
+
 1;
 __END__
 Foswiki - The Free and Open Source Wiki, http://foswiki.org/