--- deliantra/server/lib/cf/mapscript.pm	2009/01/08 19:23:44	1.3
+++ deliantra/server/lib/cf/mapscript.pm	2009/01/08 21:35:54	1.4
@@ -1,26 +1,83 @@
 #! perl
 
-# this implements the mapscript connectable
+=head1 NAME
+
+cf::mapscript
+
+=head1 DESCRIPTION
+
+This module implements the mapscript object.
+
+Map scripts are perl snippets that get executed whenever any connected
+element is triggered (e.g. a check inv, a lever etc.)
+
+=head1 ENVIRONMENT
+
+The map scripts are compiled and executed into a namespace with the
+following symbols available:
+
+=over 4
+
+=cut
 
 package safe::mapscript;
 
 use strict qw(subs vars);
 
+=item $self
+
+The mapscript object itself
+
+=item $state
+
+The state value (0 means release, <>0 means push/trigger/enable) that
+triggered the map script.
+
+=item $activator
+
+The object that was triggered (the lever, check inv element, npc etc.).
+
+=item $originator
+
+The object that triggered the activator, usually (but not always) the
+player who stepped on a check inv, pulled a lever etc. Can be C<undef>.
+
+=cut
+
 our ($self, $state, $activator, $originator);
 
+=item @obs = find $id_or_object
+
+Finds all objects with the given I<connected> C<$id>. If an object
+reference is passed, it will be returned unchanged.
+
+=cut
+
 sub find($) {
    ref $_[0] ? $_[0]
              : $self->map->find_link ($_[0])
 }
 
-sub get($) {
-   (&find)[0]->value
-}
+=item trigger $id_or_object[, $state]
+
+Triggers the linked chain with the given I<connected> id, or the connected
+chain associated with the given object (if an objetc reference is passed),
+and passes the given state (or C<1>, if missing) to it.
+
+=cut
 
 sub trigger($;$) {
    $self->map->trigger ($_[0], $#_ ? $_[1] : 1, $self);
 }
 
+=item timer $id_or_object, $seconds
+
+Starts the timer on the given mapscript object (usually, $id_or_object is
+C<$self>). When the timer expires on the mapscript object, it will trigger
+the script with C<$activator == $self> and C<$originator == undef>.
+
+=cut
+
 sub timer($$) {
    my $ob = (&find)[0];
    $ob->speed_left ($_[1] / -cf::TICK);
@@ -46,4 +103,12 @@
    )->();
 }
 
+=back
+
+=head1 EXAMPLE
+
+Have a look at F<scorn/anthonty/portgate.map> for a nontrivial example.
+
+=cut
+
 1;