--- AnyEvent/lib/AE.pm	2009/07/30 03:41:56	1.1
+++ AnyEvent/lib/AE.pm	2009/08/09 15:09:28	1.2
@@ -4,18 +4,47 @@
 
 =head1 SYNOPSIS
 
-See the L<AnyEvent> manpage for everything there is to say about AE.
+  use AnyEvent; # not AE
 
 =head1 DESCRIPTION
 
-This module implements the new simpler AnyEvent API. There is no
-description of this API here, refer to the L<AnyEvent> module for this.
+This module documents the new simpler AnyEvent API.
 
 The rationale for the new API is that experience with L<EV> shows that
-this API actually "works", despite it's simplicity. This API is (will be)
-much faster and also requires less typing.
+this API actually "works", despite it's lack of extensibility.
 
-The "old" API is still supported, and there are no plans to "switch".
+The main difference to AnyEvent is that instead of method calls, function
+calls are used, and that no named arguments are used.
+
+This makes calls to watcher creation functions really short, which can
+make a program more readable, despite the lack of named parameters.
+Function calls also allow more static type checking than method calls, so
+many mistakes are caught at compiletime with this API.
+
+Also, some backends (Perl and EV) are so fast that the method call
+overhead is very noticable (with EV it increases the time five- to
+six-fold, with Perl the method call overhead is about a factor of two).
+
+At the moment, there will be no checking (L<AnyEvent::Strict> does not
+affect his API), so the L<AnyEvent> API has a definite advantage here
+still.
+
+Note that the C<AE> API is an alternative to, not the future version of,
+the AnyEvent API. Both APIs can be used interchangably and and there are
+no plans to "switch", so if in doubt, use L<AnyEvent>'s API.
+
+As the AE API is complementary, not everything in the AnyEvent API is
+available, so you still need to use AnyEvent for the finer stuff. Also,
+you should not C<use AE> directly, C<use AnyEvent> will provide the AE
+namespace.
+
+=head2 FUNCTIONS
+
+This section briefly describes the alternative watcher
+constructors. Semantics and any methods are not described here, please
+refer to the L<AnyEvent> manpage for the details.
+
+=over 4
 
 =cut
 
@@ -23,7 +52,79 @@
 
 use AnyEvent (); # BEGIN { AnyEvent::common_sense }
 
-1;
+=item $w = AE::io $fh_or_fd, $watch_write, $cb
+
+Creates an I/O watcher that listens for read events (C<$watch_write>
+false) or write events (C<$watch_write> is true) on the file handle or
+file descriptor C<$fh_or_fd>.
+
+The callback C<$cb> is invoked as soon and as long as I/O of the type
+specified by C<$watch_write>) can be done on the file handle/descriptor.
+
+Example: wait until STDIN becomes readable.
+
+  $stdin_ready = AE::io *STDIN, 0, sub { scalar <STDIN> };
+
+Example. wait until STDOUT becomes writable and print something.
+
+  $stdout_ready = AE::io *STDOUT, 1, sub { print STDOUT "woaw\n" };
+
+=item $w = AE::timer $after, $interval, $cb
+
+Creates a timer watcher that invokes the callback C<$cb> after at least
+C<$after> second have passed (C<$after> can be negative or C<0>).
+
+If C<$interval> is C<0>, then the clalback will only be invoked once,
+otherwise it must be a positive number of seconds that specified the
+interval between successive invocations of the callback.
+
+Example: print "too late" after at least one second has passed.
+
+  $timer_once = AE::timer 1, 0, sub { print "too late\n" };
+
+Example: print "blubb" once a second, starting as soon as possible.
+
+  $timer_repeated = AE::timer 0, 1, sub { print "blubb\n" };
+
+=item $w = AE::signal $signame, $cb
+
+Invoke the callback c<$cb> each time one or more occurences of the named
+signal C<$signame> are detected.
+
+=item $w = AE::child $pid, $cb
+
+Invokes the callbakc C<$cb> when the child with the given C<$pid> exits
+(or all children, when C<$pid> is zero).
+
+The callback will get the actual pid and exit status as arguments.
+
+=item $w = AE::idle $cb
+
+Invoke the callback C<$cb> each time the event loop is "idle" (has no
+events outstanding), but do not prevent the event loop from polling for
+more events.
+
+=item $cv = AE::cv
+
+=item $cv = AE::cv { BLOCK }
+
+Create a new condition variable. The first form is identical to C<<
+AnyEvent->condvar >>, the second form additionally sets the callback (as
+if the C<cb> method is called on the condition variable).
+
+=item AE::now
+
+Returns the current event loop time (may be cached by the event loop).
+
+=item AE::now_update
+
+Ensures that the current event loop time is up to date.
+
+=item AE::time
+
+Return the current time (not cached, always consults a hardware clock).
+
+=back
 
 =head1 AUTHOR
 
@@ -32,3 +133,5 @@
 
 =cut
 
+1
+