--- deliantra/server/lib/cf.pm	2006/09/18 01:10:35	1.69
+++ deliantra/server/lib/cf.pm	2006/10/01 10:55:37	1.70
@@ -23,6 +23,32 @@
 our $TICK_WATCHER;
 our $NEXT_TICK;
 
+our %CFG;
+
+#############################################################################
+
+=head2 GLOBAL VARIABLES
+
+=over 4
+
+=item $cf::LIBDIR
+
+The perl library directory, where extensions and cf-specific modules can
+be found. It will be added to C<@INC> automatically.
+
+=item $cf::TICK
+
+The interval between server ticks, in seconds.
+
+=item %cf::CFG
+
+Configuration for the server, loaded from C</etc/crossfire/config>, or
+from wherever your confdir points to.
+
+=back
+
+=cut
+
 BEGIN {
    *CORE::GLOBAL::warn = sub {
       my $msg = join "", @_;
@@ -53,25 +79,41 @@
 my %command;
 my %extcmd;
 
-#############################################################################
-# utility functions
+=head2 UTILITY FUNCTIONS
+
+=over 4
+
+=cut
 
 use JSON::Syck (); # TODO# replace by JSON::PC once working
 
+=item $ref = cf::from_json $json
+
+Converts a JSON string into the corresponding perl data structure.
+
+=cut
+
 sub from_json($) {
    $JSON::Syck::ImplicitUnicode = 1; # work around JSON::Syck bugs
    JSON::Syck::Load $_[0]
 }
 
+=item $json = cf::to_json $ref
+
+Converts a perl data structure into its JSON representation.
+
+=cut
+
 sub to_json($) {
    $JSON::Syck::ImplicitUnicode = 0;  # work around JSON::Syck bugs
    JSON::Syck::Dump $_[0]
 }
 
+=back
+
 #############################################################################
-# "new" plug-in system
 
-=head3 EVENTS AND OBJECT ATTACHMENTS
+=head2 EVENTS AND OBJECT ATTACHMENTS
 
 =over 4
 
@@ -381,15 +423,13 @@
 
 =back
 
-=head2 methods valid for all pointers
-
-=over 4
+#############################################################################
 
-=item $object->valid
+=head2 METHODS VALID FOR ALL CORE OBJECTS
 
-=item $player->valid
+=over 4
 
-=item $map->valid
+=item $object->valid, $player->valid, $map->valid
 
 Just because you have a perl object does not mean that the corresponding
 C-level object still exists. If you try to access an object that has no
@@ -706,7 +746,12 @@
 ;
 
 #############################################################################
-# core extensions - in perl
+
+=head2 CORE EXTENSIONS
+
+Functions and methods that extend core crossfire objects.
+
+=over 4
 
 =item cf::player::exists $login
 
@@ -756,8 +801,21 @@
    $self->send ("ext " . to_json \%msg);
 }
 
+=back
+
+=cut
+
 #############################################################################
-# map scripting support
+
+=head2 SAFE SCRIPTING
+
+Functions that provide a safe environment to compile and execute
+snippets of perl code without them endangering the safety of the server
+itself. Looping constructs, I/O operators and other built-in functionality
+is not available in the safe scripting environment, and the number of
+functions and methods that cna be called is greatly reduced.
+
+=cut
 
 our $safe = new Safe "safe";
 our $safe_hole = new Safe::Hole;
@@ -768,6 +826,16 @@
 
 # here we export the classes and methods available to script code
 
+=pod
+
+The following fucntions and emthods are available within a safe environment:
+
+  cf::object contr pay_amount pay_player
+  cf::object::player player
+  cf::player peaceful
+
+=cut
+
 for (
    ["cf::object"         => qw(contr pay_amount pay_player)],
    ["cf::object::player" => qw(player)],
@@ -779,6 +847,18 @@
       for @funs;
 }
 
+=over 4
+
+=item @retval = safe_eval $code, [var => value, ...]
+
+Compiled and executes the given perl code snippet. additional var/value
+pairs result in temporary local (my) scalar variables of the given name
+that are available in the code snippet. Example:
+
+   my $five = safe_eval '$first + $second', first => 1, second => 4;
+
+=cut
+
 sub safe_eval($;@) {
    my ($code, %vars) = @_;
 
@@ -832,6 +912,8 @@
    *{"safe::$fun"} = $safe_hole->wrap ($cb);
 }
 
+=back
+
 #############################################################################
 
 =head2 EXTENSION DATABASE SUPPORT