Item14237: Minor documentation cleanup

core/lib/Foswiki/App.pm

@@ -916,7 +916,7 @@ sub run {
 
 =begin TML
 
----+++ ObjectMethod handleReques
+---+++ ObjectMethod handleRequest
 
 This is the core method of handling a HTTP request. Must never be called
 manually except for testing purposes.

core/lib/Foswiki/Config.pm

@@ -1,10 +1,5 @@
 # See bottom of file for license and copyright information
 
-package Foswiki::Exception::_expandStr::UndefVal {
-    use Foswiki::Class;
-    extends qw(Foswiki::Exception::Harmless);
-}
-
 package Foswiki::Config;
 
 =begin TML
@@ -24,7 +19,7 @@ Additionally this class implements:
    1. Some API
    
 There're two modes a =Foswiki::Class= object may be in: _data_ and _specs_. The
-difference among them is in whether =data= attribute contains a normal plain
+difference between them is in whether =data= attribute contains a normal plain
 hash (_data_ mode) or a tied one (_specs_ mode). Whichever one is active at any
 given moment of time it doesn't affect application functionality – see
 [[https://perldoc.perl.org/perltie.html][perltie]].
@@ -44,8 +39,10 @@ could be transparently verified for their validity.
 The following classes are working together to implement _specs_ mode:
 
 | *Class* | *Functionality* |
-| =Foswiki::Config::DataHash= | =data= attribute hash is tied to it; considered as top-level container class |
-| =Foswiki::Config::Node= | Represents information about a key stored in the configuration hash |
+| =Foswiki::Config::DataHash= | =data= attribute hash is tied to it;\
+  considered as top-level container class |
+| =Foswiki::Config::Node= | Represents information about a key stored in\
+  the configuration hash |
 | =Foswiki::Config::Section= | A configuration section |
 
 ---+++ Globals
@@ -71,7 +68,11 @@ A configuration *key* is a sequence of characters starting with a word character
 any character except ='.'= (a dot), or ='='= (an equal sign), or ='{'=, or ='}'=
 (curly braces).
 
-*Key path* is a sequence of configuration *keys* in either dot or curly braces
+*Spec* is a file containing information about attributes of LSC keys. The
+attributes include but not limited to key default value, description,
+config section it belongs to, etc.
+
+*Key path* is a sequence of configuration *keys* in either dot or curly braces 
 notation. For example, a dot notation:
 
 <verbatim>
@@ -203,7 +204,7 @@ Thus,a string _'${k}'_ will either expand into key =k= value; or if there is no
 such key then the result of the expansion will depend on =undef= and =undefFail=
 parameters of the =expandStr()= method.
 
----++ Attributes
+---++ ATTRIBUTES
 
 =cut
 
@@ -220,6 +221,11 @@ use Foswiki qw(urlEncode urlDecode make_params);
 use Foswiki::Configure::FileUtil;
 use Foswiki::Exception::Config;
 
+package Foswiki::Exception::_expandStr::UndefVal {
+    use Foswiki::Class;
+    extends qw(Foswiki::Exception::Harmless);
+}
+
 use Foswiki::Class qw(app extensible);
 extends qw(Foswiki::Object);
 with qw(Foswiki::Aux::Localize);
@@ -513,7 +519,7 @@ has _lscRecPos => ( is => 'rw', );
 
 =begin TML
 
----++ Methods
+---++ METHODS
 
 =cut
 

core/lib/Foswiki/Config/ItemRole.pm

@@ -283,8 +283,8 @@ sub setOpt_sources {
 ---+++ ClassMethod optionDefinitions -> @optionDefs
 
 Returns a list of option definitions for a class. Note that a option definition
-is a pair of =option => definition= where =option= is a option name; and deinition
-is a hashref of option preferences.
+is a pair of =option => definition= where =option= is a option name; and
+deinition is a hashref of option preferences.
 
 A class with =Foswiki::Config::ItemRole= applied must override this method and
 preferably combine what parent method returns with additional options the class
@@ -311,9 +311,13 @@ around optionDefinitions => sub {
 The following option preferences are supported:
 
 | *Preference* | *Description* | *Mandatory* | *Note* |
-| =arity= | Number of option parameters. Usually one but could be 0 for boolean options (then an option could be prefixed with 'no') or 2+ for some specific cases like section definition. | %Y% | |
-| =leaf= | Options is valid in a leaf node only. | | =Foswiki::Config::Node= only |
-| =dual= | Option is valid for both leaf and branch node types. | | =Foswiki::Config::Node= only |
+| =arity= | Number of option parameters. Usually one but could be 0 for boolean\
+  options (then an option could be prefixed with 'no') or 2+ for some specific\
+  cases like section definition. | %Y% | |
+| =leaf= | Options is valid in a leaf node only. | | =Foswiki::Config::Node=\
+  only |
+| =dual= | Option is valid for both leaf and branch node types. | | \
+   =Foswiki::Config::Node= only |
 
 *NOTE* Normally this method would be called once for each class. It's return
 list would be cached by =Foswiki::Config::ItemRole=.

core/lib/Foswiki/Config/Node.pm

@@ -554,7 +554,7 @@ around optionDefinitions => sub {
         default         => { arity => 1, leaf => 1, },
         display_if      => { arity => 1, leaf => 1, },
         enhance         => { arity => 0, leaf => 1, },
-        expert          => { arity => 0, leaf => 1, },
+        expert          => { arity => 0, leaf => 1, }, # TODO: Move to ItemRole?
         feedback        => { arity => 1, leaf => 1, },
         hidden          => { arity => 0, leaf => 1, },
         label           => { arity => 1, dual => 1, },

core/lib/Foswiki/Config/Section.pm

@@ -172,7 +172,8 @@ around optionDefinitions => sub {
     my $orig = shift;
     return (
         $orig->(@_),
-        expert     => { arity => 0, },
+        expert => { arity => 0, }
+        ,    # TODO Combine with node's same name option and move to ItemRole?
         modprefix  => { arity => 1, },
         expandable => { arity => 1, },
         section    => { arity => 2, },

core/lib/Foswiki/Exception.pm

@@ -11,12 +11,15 @@ Base class for all Foswiki exceptions. This is still a concept only.
 
 Basic principles behind exceptions:
 
-   1. Exceptions are using =Try::Tiny=. Use of =CPAN:Error= module is no longer
-      recommended.
-   1. Exception classes are inheriting from =Foswiki::Exception=.
-   1. =Foswiki::Exception= is an integral part of Fowiki's OO system and inheriting from =Foswiki::Object=.
-   1. =Foswiki::Exception= is utilizing =Throwable= role. Requires this module to be installed.
-   1. Exception classes inheritance shall form a tree of relationships for fine-grained error hadling.
+   1 Exceptions are using =Try::Tiny=. Use of =CPAN:Error= module is no longer
+     recommended.
+   1 Exception classes are inheriting from =Foswiki::Exception=.
+   1 =Foswiki::Exception= is an integral part of Fowiki's OO system and
+     inheriting from =Foswiki::Object=.
+   1 =Foswiki::Exception= is utilizing =Throwable= role. Requires this module
+     to be installed.
+   1 Exception classes inheritance shall form a tree of relationships for
+     fine-grained error hadling.
    
 The latter item might be illustrated with the following expample (for inherited
 classes =Foswiki::Exception= prefix is skipped for simplicity though it is

core/lib/Foswiki/Extension.pm

@@ -2,6 +2,14 @@
 
 package Foswiki::Extension;
 
+=begin TML
+
+---+!! Class Foswiki::Extension
+
+This is the base class to be inherited by _every_ new extension.
+
+=cut
+
 use Foswiki::Class qw(app callbacks);
 extends qw(Foswiki::Object);