doc refactor: events

doc/api/events.markdown

@@ -1,4 +1,4 @@
-## Events
+# Events
 
 Many objects in Node emit events: a `net.Server` emits an event each time
 a peer connects to it, a `fs.readStream` emits an event when the file is
@@ -12,7 +12,7 @@ Functions can then be attached to objects, to be executed when an event
 is emitted. These functions are called _listeners_.
 
 
-### events.EventEmitter
+## Class: events.EventEmitter
 
 To access the EventEmitter class, `require('events').EventEmitter`.
 
@@ -24,8 +24,8 @@ trace and exit the program.
 All EventEmitters emit the event `'newListener'` when new listeners are
 added.
 
-#### emitter.addListener(event, listener)
-#### emitter.on(event, listener)
+### emitter.addListener(event, listener)
+### emitter.on(event, listener)
 
 Adds a listener to the end of the listeners array for the specified event.
 
@@ -33,7 +33,7 @@ Adds a listener to the end of the listeners array for the specified event.
       console.log('someone connected!');
     });
 
-#### emitter.once(event, listener)
+### emitter.once(event, listener)
 
 Adds a **one time** listener for the event. This listener is
 invoked only the next time the event is fired, after which
@@ -43,7 +43,7 @@ it is removed.
       console.log('Ah, we have our first user!');
     });
 
-#### emitter.removeListener(event, listener)
+### emitter.removeListener(event, listener)
 
 Remove a listener from the listener array for the specified event.
 **Caution**: changes array indices in the listener array behind the listener.
@@ -56,12 +56,12 @@ Remove a listener from the listener array for the specified event.
     server.removeListener('connection', callback);
 
 
-#### emitter.removeAllListeners([event])
+### emitter.removeAllListeners([event])
 
 Removes all listeners, or those of the specified event.
 
 
-#### emitter.setMaxListeners(n)
+### emitter.setMaxListeners(n)
 
 By default EventEmitters will print a warning if more than 10 listeners are
 added for a particular event. This is a useful default which helps finding memory leaks.
@@ -69,7 +69,7 @@ Obviously not all Emitters should be limited to 10. This function allows
 that to be increased. Set to zero for unlimited.
 
 
-#### emitter.listeners(event)
+### emitter.listeners(event)
 
 Returns an array of listeners for the specified event. This array can be
 manipulated, e.g. to remove listeners.
@@ -79,12 +79,13 @@ manipulated, e.g. to remove listeners.
     });
     console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
 
-#### emitter.emit(event, [arg1], [arg2], [...])
+### emitter.emit(event, [arg1], [arg2], [...])
 
 Execute each of the listeners in order with the supplied arguments.
 
-#### Event: 'newListener'
+### Event: 'newListener'
 
-`function (event, listener) { }`
+* `event` {String} The event name
+* `listener` {Function} The event handler function
 
 This event is emitted any time someone adds a new listener.