Add documentation

src/protocolP2P/CodeType.java

@@ -1,4 +1,11 @@
 package protocolP2P;
+
+/** Request/Response code's type enum.
+ * @author	Louis Royer
+ * @author	Flavien Haas
+ * @author	JS Auge
+ * @version	1.0
+ */
 public enum CodeType {
 	REQUEST,
 	RESPONSE,

src/protocolP2P/FileList.java

@@ -5,14 +5,35 @@ import protocolP2P.RequestResponseCode;
 import exception.ProtocolError;
 import exception.InternalError;
 
+/** Representation of payload for list response.
+ * @author	Louis Royer
+ * @author	Flavien Haas
+ * @author	JS Auge
+ * @version	1.0
+ */
 public class FileList extends Payload {
 	private final static RequestResponseCode requestResponseCode = RequestResponseCode.LIST_RESPONSE;
 	private ArrayList<String> content;
 
-	public FileList(ArrayList<String> content) {
+	/** Constructor (typically used by the server) with an ArrayList parameter containing
+	 * filenames.
+	 * @param content	a list of files. Must not be empty.
+	 * @throws	InternalError
+	 */
+	public FileList(ArrayList<String> content) throws InternalError {
+		/* assert to help debugging */
+		assert !content.isEmpty() : "Payload size of FileList must not be empty, use EmptyDirectory from Payload instead";
+		if (content.isEmpty()) {
+			throws new InternalError();
+		}
 		this.content = content;
 	}
 
+	/** Constructor (typically used by client) with a byte[] parameter containing the datagram received.
+	 * @param datagram	the full datagram received
+	 * @throws	ProtocolError
+	 * @throws	InternalError
+	 */
 	public FileList(byte[] datagram) throws ProtocolError, InternalError {
 		//TODO
 		/* assert to help debugging */
@@ -24,8 +45,12 @@ public class FileList extends Payload {
 		int size = getPayloadSize(datagram);
 	}
 
-	/** To datagram with padding */
+	/** Returns a byte[] containing datagram with padding.
-	public byte[] toDatagram() {
+	 * This datagram is still incomplete and should not be send directly.
+	 * ProtocolP2PDatagram will use this method to generate the complete datagram.
+	 * @return datagram with padding
+	 */
+	protected byte[] toDatagram() {
 		byte[] datagram; // java initialize all to zero
 		// size is keep blank (ProtocolP2PDatagram will handle it)
 		// set request/response code

src/protocolP2P/FilePart.java

@@ -4,6 +4,12 @@ import protocolP2P.RequestResponseCode;
 import exception.ProtocolError;
 import exception.InternalError;
 
+/** Representation of payload for load response.
+ * @author	Louis Royer
+ * @author	Flavien Haas
+ * @author	JS Auge
+ * @version	1.0
+ */
 public class FilePart extends Payload {
 	private static final RequestResponseCode requestResponseCode = RequestResponseCode.LOAD_RESPONSE;
 	private String filename;
@@ -11,6 +17,12 @@ public class FilePart extends Payload {
 	private int offset;
 	private byte[] partialContent;
 
+	/** Constructor (typically used by server) with informations about file part to send as parameters.
+	 * @param filename	name of the file to send
+	 * @param totalSize	total size of the file to send
+	 * @param offset	where in the file begins the part we are sending
+	 * @param partialContent	content of the file we send
+	 */
 	public FilePart(String filename, int totalSize, int offset, byte[] partialContent) {
 		this.filename = filename;
 		this.totalSize = totalSize;
@@ -18,6 +30,11 @@ public class FilePart extends Payload {
 		this.partialContent = partialContent;
 	}
 
+	/** Constructor (typically used by client) with datagram received as parameter.
+	 * @param datagram	the full datagram received
+	 * @throws	ProtocolError
+	 * @throws	InternalError
+	 */
 	public FilePart(byte[] datagram) throws ProtocolError, InternalError {
 		//TODO
 		/* assert to help debugging */
@@ -29,7 +46,11 @@ public class FilePart extends Payload {
 		int size = getPayloadSize(datagram);
 	}
 
-	/** To datagram with padding */
+	/** Returns a byte[] containing datagram with padding.
+	 * This datagram is still incomplete and should not be send directly.
+	 * ProtocolP2PDatagram will use this method to generate the complete datagram.
+	 * @return datagram with padding
+	 */
 	public byte[] toDatagram() {
 		byte[] datagram; // java initialize all to zero
 		// size is keep blank (ProtocolP2PDatagram will handle it)

src/protocolP2P/Payload.java

@@ -4,13 +4,21 @@ import protocolP2P.FilePart;
 import protocolP2P.FileList;
 import exception.ProtocolError;
 import exception.InternalError;
-
+/** Representation of payload. If payload has a size, use subclasses instead.
+ * @author	Louis Royer
+ * @author	Flavien Haas
+ * @author	JS Auge
+ * @version	1.0
+ */
 public class Payload {
 	private RequestResponseCode requestResponseCode;
 	protected final static int PAYLOAD_SIZE_POSITON = 4;
 	protected final static int PAYLOAD_START_POSITION = 8;
 
-	/** To create request/response with a payload size of zero */
+	/** Consructor used to create Payload with a payload size of zero using a RRCode.
+	 * @param requestResponseCode	Request/Response code associated with the payload
+	 * @throws	InternalError
+	 */
 	public Payload(RequestResponseCode requestResponseCode) throws InternalError {
 		/* asserts to help debugging */
 		assert requestResponseCode != requestResponseCode.LIST_RESPONSE : "LIST_RESPONSE must use FilePart class";
@@ -19,6 +27,12 @@ public class Payload {
 		checkRequestResponseCode(); // this can throw InternalError
 	}
 
+	/** Constructor used to create a Payload (when no more specific subclasses exists) using datagram as parameter.
+	 * If payload size is not empty, using subclass is required.
+	 * @param datagram	the full datagram received
+	 * @throws	ProtocolError
+	 * @throws	InternalError
+	 */
 	public Payload(byte[] datagram) throws ProtocolError, InternalError {
 		/* asserts to help debugging */
 		assert RequestResponseCode.fromCode(datagram[RequestResponseCode.RRCODE_POSITION]) != RequestResponseCode.LIST_RESPONSE : "LIST_RESPONSE must use FilePart class";
@@ -27,6 +41,9 @@ public class Payload {
 		checkRequestResponseCode(); // this can throw InternalError
 	}
 
+	/** Used to check RRCode used is compatible with this class use, or if a more specific subclass is required.
+	 * @throws	InternalError
+	 */ 
 	private void checkRequestResponseCode() throws InternalError {
 		/* Incorrect use cases (use subclasses instead) */
 		if (requestResponseCode == RequestResponseCode.LIST_RESPONSE || requestResponseCode == RequestResponseCode.LOAD_RESPONSE) {
@@ -34,7 +51,11 @@ public class Payload {
 		}
 	}
 	
-	/** Payload with padding */
+	/** Returns a byte[] containing datagram with padding.
+	 * This datagram is still incomplete and should not be send directly.
+	 * ProtocolP2PDatagram will use this method to generate the complete datagram.
+	 * @return datagram with padding
+	 */
 	public byte[] toDatagram() {
 		byte [] datagram = new byte[8]; // java initialize all to zero
 		// size is keep blank (ProtocolP2PDatagram will handle it)
@@ -44,6 +65,11 @@ public class Payload {
 		// payload size is 0 (this is what java have initialized datagram)
 	}
 
+	/** Set payload’s size in a datagram.
+	 * @param size	integer representing payload size
+	 * @param datagram	datagram to be completed
+	 * @return	datagram with payload’s size set
+	 */ 
 	protected static byte[] setPayloadSize(int size, byte[] datagram) { 
 		for(int i=0;i<4;i++) {
 				datagram[Payload.PAYLOAD_SIZE_POSITON + i] = (byte) (size >> (8 * (3 - i)) & 0xFF);
@@ -51,7 +77,11 @@ public class Payload {
 		}
 		return datagram;
 	}
-	
+
+	/** Get payload’s size from a datagram.
+	 * @param datagram	the full datagram received
+	 * @return	integer representing payload size
+	 */
 	protected static int getPayloadSize(byte[] datagram) {
 		int size = 0;
 		for(int i=0;i<4;i++) {

src/protocolP2P/ProtocolP2PDatagram.java

@@ -6,17 +6,31 @@ import protocolP2P.RequestResponseCode;
 import java.util.ArrayList;
 import java.lang.Byte;
 
+/** Representation of datagram.
+ * @author	Louis Royer
+ * @author	Flavien Haas
+ * @author	JS Auge
+ * @version	1.0
+ */
 public class ProtocolP2PDatagram {
 	private final static byte PROTOCOL_VERSION = 0x11;
 	private final static int VERSION_POSITON = 0;
 	private byte version;
 	private Payload payload;
 
+	/** Constructor with payload parameter (typically used when sending datagram).
+	 * @param payload	the payload associated with the datagram to send
+	 */
 	public ProtocolP2PDatagram(Payload payload) {
 		version = PROTOCOL_VERSION;
 		this.payload = payload;
 	}
 
+	/** Constructor with datagram as byte[] parameter (typically used when receiving datagram).
+	 * @param datagram	the full datagram received
+	 * @throws	ProtocolError
+	 * @throws	VersionError
+	 */
 	public ProtocolP2PDatagram(byte[] datagram) throws ProtocolError, VersionError {
 		// unwrap version
 		version = datagram[VERSION_POSITON];
@@ -35,16 +49,26 @@ public class ProtocolP2PDatagram {
 			}
 	}
 
+	/** Returns a byte[] containing full datagram (typically used when sending datagram).
+	 * This datagram is still complete and ready to be send.
+	 * @return the full datagram to send
+	 */
 	public byte[] toDatagram() {
 		byte[] datagram = payload.toDatagram();
 		datagram[VERSION_POSITON] = version;
 		return datagram;
 	}
 
+	/** Returns Payload associated with the datagram.
+	 * @return	payload associated with the datagram
+	 */
 	public Payload getPayload() {
 		return payload;
 	}
 
+	/** Used to check protocol version when a datagram is constructed from bytes[].
+	 * @throws	VersionError
+	 */
 	private void checkProtocolVersion() throws VersionError {
 		if (PROTOCOL_VERSION != version) {
 			throw new VersionError();