diff --git a/src/main/java/com/github/dockerjava/api/model/Link.java b/src/main/java/com/github/dockerjava/api/model/Link.java
index 9aa762a8a..4416dca0c 100644
--- a/src/main/java/com/github/dockerjava/api/model/Link.java
+++ b/src/main/java/com/github/dockerjava/api/model/Link.java
@@ -1,9 +1,16 @@
-
 package com.github.dockerjava.api.model;
 
 import org.apache.commons.lang.builder.EqualsBuilder;
 import org.apache.commons.lang.builder.HashCodeBuilder;
 
+/**
+ * Represents a network link between two Docker containers.
+ * The container with the name {@link #getName()} is made available in the
+ * target container with the aliased name {@link #getAlias()}.
+ * This involves creating an entry in <code>/etc/hosts</code> and some environment
+ * variables in the target container as well as creating a network bridge between
+ * both containers.
+ */
 public class Link
 {
 
@@ -11,23 +18,46 @@ public class Link
 
 	private final String alias;
 
+	/**
+	 * Creates a {@link Link} for the container with the given name and an aliased
+	 * name for use in the target container.
+	 * 
+	 * @param name the name of the container that you want to link into the target
+	 *        container
+	 * @param alias the aliased name under which the linked container will be available
+	 *        in the target container
+	 */
 	public Link(final String name, final String alias)
 	{
 		this.name = name;
 		this.alias = alias;
 	}
 
+	/**
+	 * @return the name of the container that is linked into the target container
+	 */
 	public String getName()
 	{
 		return name;
 	}
 
+	/**
+	 * @return the aliased name under which the linked container will be available
+	 *         in the target container  
+	 */
 	public String getAlias()
 	{
 		return alias;
 	}
 
-	public static Link parse(final String serialized)
+	/**
+	 * Parses a textual link specification (as used by the Docker CLI) to a {@link Link}.
+	 * 
+	 * @param serialized the specification, e.g. <code>name:alias</code>
+	 * @return a {@link Link} matching the specification
+	 * @throws IllegalArgumentException if the specification cannot be parsed
+	 */
+	public static Link parse(final String serialized) throws IllegalArgumentException
 	{
 		try {
 			final String[] parts = serialized.split(":");
@@ -36,11 +66,11 @@ public static Link parse(final String serialized)
 				return new Link(parts[0], parts[1]);
 			}
 			default: {
-				throw new RuntimeException("Error parsing Link '" + serialized + "'");
+				throw new IllegalArgumentException();
 			}
 			}
 		} catch (final Exception e) {
-			throw new RuntimeException("Error parsing Link '" + serialized + "'");
+			throw new IllegalArgumentException("Error parsing Link '" + serialized + "'");
 		}
 	}
 
@@ -60,4 +90,16 @@ public int hashCode()
 		return new HashCodeBuilder().append(name).append(alias).toHashCode();
 	}
 
+	/**
+	 * Returns a string representation of this {@link Link} suitable
+	 * for inclusion in a JSON message.
+	 * The format is <code>name:alias</code>, like the argument in {@link #parse(String)}.
+	 * 
+	 * @return a string representation of this {@link Link}
+	 */
+	@Override
+	public String toString() {
+		return name + ":" + alias;
+	}
+
 }
diff --git a/src/main/java/com/github/dockerjava/api/model/Links.java b/src/main/java/com/github/dockerjava/api/model/Links.java
index 499e84401..b0d0cc8df 100644
--- a/src/main/java/com/github/dockerjava/api/model/Links.java
+++ b/src/main/java/com/github/dockerjava/api/model/Links.java
@@ -45,8 +45,7 @@ public void serialize(final Links links, final JsonGenerator jsonGen, final Seri
 		{
 			jsonGen.writeStartArray();
 			for (final Link link : links.getLinks()) {
-				final String s = link.getName() + ":" + link.getAlias();
-				jsonGen.writeString(s);
+				jsonGen.writeString(link.toString());
 			}
 			jsonGen.writeEndArray();
 		}
diff --git a/src/test/java/com/github/dockerjava/api/model/LinkTest.java b/src/test/java/com/github/dockerjava/api/model/LinkTest.java
new file mode 100644
index 000000000..c42af9da6
--- /dev/null
+++ b/src/test/java/com/github/dockerjava/api/model/LinkTest.java
@@ -0,0 +1,33 @@
+package com.github.dockerjava.api.model;
+
+import static org.testng.Assert.assertEquals;
+
+import org.testng.annotations.Test;
+
+public class LinkTest {
+
+	@Test
+	public void parse() {
+		Link link = Link.parse("name:alias");
+		assertEquals(link.getName(), "name");
+		assertEquals(link.getAlias(), "alias");
+	}
+
+	@Test(expectedExceptions = IllegalArgumentException.class,
+			expectedExceptionsMessageRegExp = "Error parsing Link 'nonsense'")
+	public void parseInvalidInput() {
+		Link.parse("nonsense");
+	}
+
+	@Test(expectedExceptions = IllegalArgumentException.class, 
+			expectedExceptionsMessageRegExp = "Error parsing Link 'null'")
+	public void parseNull() {
+		Link.parse(null);
+	}
+
+	@Test
+	public void stringify() {
+		assertEquals(Link.parse("name:alias").toString(), "name:alias");
+	}
+
+}