Add some documentation to `haxe.io.Output`

std/haxe/io/Output.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2005-2012 Haxe Foundation
+ * Copyright (C)2005-2014 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -23,22 +23,38 @@ package haxe.io;
 
 /**
 	An Output is an abstract write. A specific output implementation will only
-	have to override the [writeChar] and maybe the [write], [flush] and [close]
+	have to override the [writeByte] and maybe the [write], [flush] and [close]
 	methods. See [File.write] and [String.write] for two ways of creating an
 	Output.
 **/
 class Output {
 	private static var LN2 = Math.log(2);
+
+	/**
+		Endianness (word byte order) used when writing numbers.
+
+		If `true`, big-endian is used, otherwise `little-endian` is used.
+	**/
 	public var bigEndian(default, set) : Bool;
 
 	#if java
 	private var helper:java.nio.ByteBuffer;
 	#end
 
+	/**
+		Write one byte.
+	**/
 	public function writeByte( c : Int ) : Void {
 		throw "Not implemented";
 	}
 
+	/**
+		Write `len` bytes from `s` starting by position specified by `pos`.
+
+		Returns the actual length of written data that can differ from `len`.
+
+		See `writeFullBytes` that tries to write the exact amount of specified bytes.
+	**/
 	public function writeBytes( s : Bytes, pos : Int, len : Int ) : Int {
 		var k = len;
 		var b = s.getData();
@@ -62,9 +78,17 @@ class Output {
 		return len;
 	}
 
+	/**
+		Flush any buffered data.
+	**/
 	public function flush() {
 	}
 
+	/**
+		Close the output.
+
+		Behaviour while writing after calling this method is unspecified.
+	**/
 	public function close() {
 	}
 
@@ -75,6 +99,9 @@ class Output {
 
 	/* ------------------ API ------------------ */
 
+	/**
+		Write all bytes stored in `s`.
+	**/
 	public function write( s : Bytes ) : Void {
 		var l = s.length;
 		var p = 0;
@@ -86,6 +113,11 @@ class Output {
 		}
 	}
 
+	/**
+		Write `len` bytes from `s` starting by position specified by `pos`.
+
+		Unlike `writeBytes`, this method tries to write the exact `len` amount of bytes.
+	**/
 	public function writeFullBytes( s : Bytes, pos : Int, len : Int ) {
 		while( len > 0 ) {
 			var k = writeBytes(s,pos,len);
@@ -94,6 +126,11 @@ class Output {
 		}
 	}
 
+	/**
+		Write `x` as 32-bit floating point number.
+
+		Endianness is specified by the `bigEndian` property.
+	**/
 	public function writeFloat( x : Float ) {
 		#if neko
 		write(untyped new Bytes(4,_float_bytes(x,bigEndian)));
@@ -148,6 +185,11 @@ class Output {
 		#end
 	}
 
+	/**
+		Write `x` as 64-bit double-precision floating point number.
+
+		Endianness is specified by the `bigEndian` property.
+	**/
 	public function writeDouble( x : Float ) {
 		#if neko
 		write(untyped new Bytes(8,_double_bytes(x,bigEndian)));
@@ -225,17 +267,30 @@ class Output {
 		#end
 	}
 
+	/**
+		Write `x` as 8-bit signed integer.
+	**/
 	public function writeInt8( x : Int ) {
 		if( x < -0x80 || x >= 0x80 )
 			throw Error.Overflow;
 		writeByte(x & 0xFF);
 	}
 
+	/**
+		Write `x` as 16-bit signed integer.
+
+		Endianness is specified by the `bigEndian` property.
+	**/
 	public function writeInt16( x : Int ) {
 		if( x < -0x8000 || x >= 0x8000 ) throw Error.Overflow;
 		writeUInt16(x & 0xFFFF);
 	}
 
+	/**
+		Write `x` as 16-bit unsigned integer.
+
+		Endianness is specified by the `bigEndian` property.
+	**/
 	public function writeUInt16( x : Int ) {
 		if( x < 0 || x >= 0x10000 ) throw Error.Overflow;
 		if( bigEndian ) {
@@ -247,11 +302,21 @@ class Output {
 		}
 	}
 
+	/**
+		Write `x` as 24-bit signed integer.
+
+		Endianness is specified by the `bigEndian` property.
+	**/
 	public function writeInt24( x : Int ) {
 		if( x < -0x800000 || x >= 0x800000 ) throw Error.Overflow;
 		writeUInt24(x & 0xFFFFFF);
 	}
 
+	/**
+		Write `x` as 24-bit unsigned integer.
+
+		Endianness is specified by the `bigEndian` property.
+	**/
 	public function writeUInt24( x : Int ) {
 		if( x < 0 || x >= 0x1000000 ) throw Error.Overflow;
 		if( bigEndian ) {
@@ -265,6 +330,11 @@ class Output {
 		}
 	}
 
+	/**
+		Write `x` as 32-bit signed integer.
+
+		Endianness is specified by the `bigEndian` property.
+	**/
 	public function writeInt32( x : Int ) {
 		if( bigEndian ) {
 			writeByte( x >>> 24 );
@@ -280,7 +350,8 @@ class Output {
 	}
 
 	/**
-		Inform that we are about to write at least a specified number of bytes.
+		Inform that we are about to write at least `nbytes` bytes.
+
 		The underlying implementation can allocate proper working space depending
 		on this information, or simply ignore it. This is not a mandatory call
 		but a tip and is only used in some specific cases.
@@ -288,6 +359,12 @@ class Output {
 	public function prepare( nbytes : Int ) {
 	}
 
+	/**
+		Read all available data from `i` and write it.
+
+		The `bufsize` optional argument specifies the size of chunks by
+		which data is read and written. Its default value is 4096.
+	**/
 	public function writeInput( i : Input, ?bufsize : Int ) {
 		if( bufsize == null )
 			bufsize = 4096;
@@ -310,6 +387,9 @@ class Output {
 		}
 	}
 
+	/**
+		Write `s` string.
+	**/
 	public function writeString( s : String ) {
 		#if neko
 		var b = untyped new Bytes(s.length,s.__s);