juneau-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jamesbog...@apache.org
Subject juneau git commit: Javadoc updates.
Date Sun, 14 Jan 2018 00:05:15 GMT
Repository: juneau
Updated Branches:
  refs/heads/master 1ff14b27d -> d7562f070


Javadoc updates.

Project: http://git-wip-us.apache.org/repos/asf/juneau/repo
Commit: http://git-wip-us.apache.org/repos/asf/juneau/commit/d7562f07
Tree: http://git-wip-us.apache.org/repos/asf/juneau/tree/d7562f07
Diff: http://git-wip-us.apache.org/repos/asf/juneau/diff/d7562f07

Branch: refs/heads/master
Commit: d7562f0700f9359fc9840188045ccbac0213f9e1
Parents: 1ff14b2
Author: JamesBognar <jamesbognar@apache.org>
Authored: Sat Jan 13 19:04:58 2018 -0500
Committer: JamesBognar <jamesbognar@apache.org>
Committed: Sat Jan 13 19:04:58 2018 -0500

----------------------------------------------------------------------
 .../java/org/apache/juneau/ini/ConfigFile.java  |  8 +--
 .../apache/juneau/ini/ConfigFileBuilder.java    |  2 +-
 .../java/org/apache/juneau/jena/RdfCommon.java  |  4 +-
 .../org/apache/juneau/jena/RdfSerializer.java   |  5 +-
 .../apache/juneau/encoders/EncoderGroup.java    |  2 +-
 .../org/apache/juneau/parser/ParserGroup.java   |  2 +-
 .../juneau/serializer/SerializerGroup.java      |  2 +-
 .../org/apache/juneau/transform/Surrogate.java  |  4 +-
 .../java/org/apache/juneau/uon/ParamFormat.java |  3 +-
 .../org/apache/juneau/uon/UonSerializer.java    | 71 +++++++++++++++-----
 .../urlencoding/UrlEncodingSerializer.java      | 45 +++++++------
 .../UrlEncodingSerializerBuilder.java           |  2 +-
 .../juneau/yaml/proto/YamlSerializer.java       |  2 +-
 .../apache/juneau/rest/client/RestClient.java   | 11 +--
 14 files changed, 106 insertions(+), 57 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFile.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFile.java
b/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFile.java
index 69aec1e..15fb302 100644
--- a/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFile.java
+++ b/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFile.java
@@ -304,7 +304,7 @@ public abstract class ConfigFile implements Map<String,Section>
{
 	 *
 	 * <h5 class='section'>Examples:</h5>
 	 * <p class='bcode'>
-	 * 	ConfigFile cf = <jk>new</jk> ConfigFileBuilder().build(<js>"MyConfig.cfg"</js>);
+	 * 	ConfigFile cf = ConfigFile.<jsm>create</jsm>().build(<js>"MyConfig.cfg"</js>);
 	 *
 	 * 	<jc>// Parse into a linked-list of strings.</jc>
 	 * 	List l = cf.getObject(<js>"MySection/myListOfStrings"</js>, LinkedList.<jk>class</jk>,
String.<jk>class</jk>);
@@ -390,7 +390,7 @@ public abstract class ConfigFile implements Map<String,Section>
{
 	 *
 	 * <h5 class='section'>Examples:</h5>
 	 * <p class='bcode'>
-	 * 	ConfigFile cf = <jk>new</jk> ConfigFileBuilder().build(<js>"MyConfig.cfg"</js>);
+	 * 	ConfigFile cf = ConfigFile.<jsm>create</jsm>().build(<js>"MyConfig.cfg"</js>);
 	 *
 	 * 	<jc>// Parse into a string.</jc>
 	 * 	String s = cf.getObject(<js>"MySection/mySimpleString"</js>, String.<jk>class</jk>);
@@ -950,7 +950,7 @@ public abstract class ConfigFile implements Map<String,Section>
{
 	 *
 	 * <h6 class='figure'>Example usage</h6>
 	 * <p class='bcode'>
-	 * 	ConfigFile cf = <jk>new</jk> ConfigFileBuilder().build(<js>"MyConfig.cfg"</js>);
+	 * 	ConfigFile cf = ConfigFile.<jsm>create</jsm>().build(<js>"MyConfig.cfg"</js>);
 	 * 	Address myAddress = cf.getSectionAsBean(<js>"MySection"</js>, Address.<jk>class</jk>);
 	 * </p>
 	 *
@@ -1024,7 +1024,7 @@ public abstract class ConfigFile implements Map<String,Section>
{
 	 *
 	 * <h6 class='figure'>Example usage</h6>
 	 * <p class='bcode'>
-	 * 	ConfigFile cf = <jk>new</jk> ConfigFileBuilder().build(<js>"MyConfig.cfg"</js>);
+	 * 	ConfigFile cf = ConfigFile.<jsm>create</jsm>().build(<js>"MyConfig.cfg"</js>);
 	 *
 	 * 	MyConfigInterface ci = cf.getSectionAsInterface(<js>"MySection"</js>, MyConfigInterface.<jk>class</jk>);
 	 *

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFileBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFileBuilder.java
b/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFileBuilder.java
index 36079e8..e58714e 100644
--- a/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFileBuilder.java
+++ b/juneau-core/juneau-config/src/main/java/org/apache/juneau/ini/ConfigFileBuilder.java
@@ -31,7 +31,7 @@ import org.apache.juneau.utils.*;
  *
  * <h5 class='topic'>Example</h5>
  * <p class='bcode'>
- * 	ConfigFile cf = <jk>new</jk> ConfigFileBuilder().build(<js>"MyConfig.cfg"</js>);
+ * 	ConfigFile cf = ConfigFile.<jsm>create</jsm>().build(<js>"MyConfig.cfg"</js>);
  * 	String setting = cf.get(<js>"MySection/mysetting"</js>);
  * </p>
  */

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfCommon.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfCommon.java
b/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfCommon.java
index c962179..bacfacd 100644
--- a/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfCommon.java
+++ b/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfCommon.java
@@ -728,8 +728,8 @@ public interface RdfCommon {
 	 *
 	 * <h5 class='section'>Example:</h5>
 	 * <p class='bcode'>
-	 * 	WriterSerializer s = <jk>new</jk> RdfSerializerBuilder().xmlabbrev().looseCollections(<jk>true</jk>).build();
-	 * 	ReaderParser p = <jk>new</jk> RdfParserBuilder().xml().looseCollections(<jk>true</jk>).build();
+	 * 	WriterSerializer s = RdfSerializer.<jsm>create</jsm>().xmlabbrev().looseCollections(<jk>true</jk>).build();
+	 * 	ReaderParser p = RdfParser.<jsm>create</jsm>().xml().looseCollections(<jk>true</jk>).build();
 	 *
 	 * 	List&lt;MyBean&gt; l = createListOfMyBeans();
 	 *

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfSerializer.java
b/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfSerializer.java
index 9b8c3e2..82312a6 100644
--- a/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfSerializer.java
+++ b/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfSerializer.java
@@ -70,9 +70,6 @@ public class RdfSerializer extends WriterSerializer implements RdfCommon
{
 	 * <p>
 	 * If <jk>true</jk>, then <js>"_type"</js> properties will be added
to beans if their type cannot be inferred 
 	 * through reflection.
-	 * This is used to recreate the correct objects during parsing if the object types cannot
be inferred.
-	 * For example, when serializing a {@code Map<String,Object>} field, where the bean
class cannot be determined 
-	 * from the value type.
 	 * 
 	 * <p>
 	 * When present, this value overrides the {@link #SERIALIZER_addBeanTypeProperties} setting
and is
@@ -118,7 +115,7 @@ public class RdfSerializer extends WriterSerializer implements RdfCommon
{
 	 * <p>
 	 * When enabled an RDF property <code>http://www.apache.org/juneau/root</code>
is added with a value of <js>"true"</js>
 	 * to identify the root node in the graph.
-	 * This helps locate the root node during parsing.
+	 * <br>This helps locate the root node during parsing.
 	 * 
 	 * <p>
 	 * If disabled, the parser has to search through the model to find any resources without
incoming predicates to 

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/encoders/EncoderGroup.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/encoders/EncoderGroup.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/encoders/EncoderGroup.java
index f1ddd88..f7570ae 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/encoders/EncoderGroup.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/encoders/EncoderGroup.java
@@ -43,7 +43,7 @@ import org.apache.juneau.http.*;
  * <h5 class='section'>Example:</h5>
  * <p class='bcode'>
  * 	<jc>// Create an encoder group with support for gzip compression.</jc>
- * 	EncoderGroup g = <jk>new</jk> EncoderGroupBuilder().append(GzipEncoder.<jk>class</jk>).build();
+ * 	EncoderGroup g = EncoderGroup.<jsm>create</jsm>().append(GzipEncoder.<jk>class</jk>).build();
  *
  * 	<jc>// Should return "gzip"</jc>
  * 	String matchedCoding = g.findMatch(<js>"compress;q=1.0, gzip;q=0.8, identity;q=0.5,
*;q=0"</js>);

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserGroup.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserGroup.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserGroup.java
index aa8229d..80b0e69 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserGroup.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserGroup.java
@@ -50,7 +50,7 @@ import org.apache.juneau.http.*;
  * <h5 class='section'>Example:</h5>
  * <p class='bcode'>
  * 	<jc>// Construct a new parser group builder</jc>
- * 	ParserGroupBuilder b = <jk>new</jk> ParserGroupBuilder();
+ * 	ParserGroupBuilder b = ParserGroup.<jsm>create</jsm>();
  *
  * 	<jc>// Add some parsers to it</jc>
  * 	b.append(JsonParser.<jk>class</jk>, XmlParser.<jk>class</jk>);

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/SerializerGroup.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/SerializerGroup.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/SerializerGroup.java
index 6d6f950..a32aaa2 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/SerializerGroup.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/SerializerGroup.java
@@ -48,7 +48,7 @@ import org.apache.juneau.http.*;
  * <h5 class='section'>Example:</h5>
  * <p class='bcode'>
  * 	<jc>// Construct a new serializer group</jc>
- * 	SerializerGroup g = <jk>new</jk> SerializerGroupBuilder();
+ * 	SerializerGroup g = SerializerGroup.<jsm>create</jsm>();
  * 		.append(JsonSerializer.<jk>class</jk>, XmlSerializer.<jk>class</jk>);
<jc>// Add some serializers to it</jc>
  * 		.ws().pojoSwaps(CalendarSwap.ISO8601DT.<jk>class</jk>) <jc>// Change
settings for all serializers in the group.</jc>
  * 		.build();

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/Surrogate.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/Surrogate.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/Surrogate.java
index 6fc3b14..aaf7e40 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/Surrogate.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/Surrogate.java
@@ -72,8 +72,8 @@ import org.apache.juneau.*;
  * <p class='bcode'>
  * 	<ja>@Test</ja>
  * 	<jk>public void</jk> test() <jk>throws</jk> Exception {
- * 		JsonSerializer s = <jk>new</jk> JsonSerializerBuilder().simple().pojoSwaps(MySurrogate.<jk>class</jk>).build();
- * 		JsonParser p = <jk>new</jk> JsonParserBuilder().pojoSwaps(MySurrogate.<jk>class</jk>).build();
+ * 		JsonSerializer s = JsonSerializer.<jsm>create</jsm>().simple().pojoSwaps(MySurrogate.<jk>class</jk>).build();
+ * 		JsonParser p = JsonParser.<jsm>create</jsm>().pojoSwaps(MySurrogate.<jk>class</jk>).build();
  * 		String r;
  * 		Normal n = Normal.<jsm>create</jsm>();
  *

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/ParamFormat.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/ParamFormat.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/ParamFormat.java
index 271d802..9b3d642 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/ParamFormat.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/ParamFormat.java
@@ -34,11 +34,12 @@ public enum ParamFormat {
 	 *
 	 * <p>
 	 * Strings will never be quoted or escaped.
+	 * <br>Maps and array constructs (<js>"(...)"</js>, <js>"@(...)"</js>)
will never be used.
 	 *
 	 * <p>
 	 * Note that this can cause errors during parsing if you're using the URL-encoding parser
to parse the results since
 	 * UON constructs won't be differentiable.
-	 * However, this is not an issue if you're simply creating queries or form posts against
3rd-party interfaces.
+	 * <br>However, this is not an issue if you're simply creating queries or form posts
against 3rd-party interfaces.
 	 */
 	PLAINTEXT;
 }

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializer.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializer.java
index 1a93afe..60d6808 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializer.java
@@ -141,9 +141,6 @@ public class UonSerializer extends WriterSerializer {
 	 * <p>
 	 * If <jk>true</jk>, then <js>"_type"</js> properties will be added
to beans if their type cannot be inferred
 	 * through reflection.
-	 * This is used to recreate the correct objects during parsing if the object types cannot
be inferred.
-	 * For example, when serializing a {@code Map<String,Object>} field, where the bean
class cannot be determined from
-	 * the value type.
 	 *
 	 * <p>
 	 * When present, this value overrides the {@link #SERIALIZER_addBeanTypeProperties} setting
and is
@@ -173,8 +170,30 @@ public class UonSerializer extends WriterSerializer {
 	 *
 	 * <p>
 	 * If <jk>true</jk>, non-valid URI characters will be converted to <js>"%xx"</js>
sequences.
-	 * Set to <jk>false</jk> if parameter value is being passed to some other code
that will already perform
+	 * <br>Set to <jk>false</jk> if parameter value is being passed to some
other code that will already perform
 	 * URL-encoding of non-valid URI characters.
+	 * 
+	 * <h5 class='section'>Example:</h5>
+	 * <p class='bcode'>
+	 * 	<jc>// Create a non-encoding UON serializer.</jc>
+	 * 	UonSerializer s1 = UonSerializer.
+	 * 		.<jsm>create</jsm>()
+	 * 		.build();
+	 * 	
+	 * 	<jc>// Create an encoding UON serializer.</jc>
+	 * 	UonSerializer s2 = UonSerializer.
+	 * 		.<jsm>create</jsm>()
+	 * 		.encoding()
+	 * 		.build();
+	 * 	
+	 * 	ObjectMap m = <jk>new</jk> ObjectMap().append("foo", "foo bar");
+	 * 	
+	 * 	<jc>// Produces: "(foo=foo bar)"</jc>
+	 * 	String uon1 = s1.serialize(m)
+	 * 	
+	 * 	<jc>// Produces: "(foo=foo%20bar)"</jc>
+	 * 	String uon2 = s2.serialize(m)
+	 * </p>
 	 */
 	public static final String UON_encoding = PREFIX + "encoding.b";
 
@@ -197,6 +216,37 @@ public class UonSerializer extends WriterSerializer {
 	 * <h5 class='section'>Description:</h5>
 	 * <p>
 	 * Specifies the format to use for URL GET parameter keys and values.
+	 * 
+	 * <p>
+	 * Possible values:
+	 * <ul>
+	 * 	<li class='jf'>{@link ParamFormat#UON} - Use UON notation for parameters.
+	 * 	<li class='jf'>{@link ParamFormat#PLAINTEXT} - Use plain text for parameters.
+	 * </ul>
+	 * 
+	 * <h5 class='section'>Example:</h5>
+	 * <p class='bcode'>
+	 * 	<jc>// Create a normal UON serializer.</jc>
+	 * 	UonSerializer s1 = UonSerializer.
+	 * 		.<jsm>create</jsm>()
+	 * 		.build();
+	 * 	
+	 * 	<jc>// Create a plain-text UON serializer.</jc>
+	 * 	UonSerializer s2 = UonSerializer.
+	 * 		.<jsm>create</jsm>()
+	 * 		.paramFormat(<jsf>PLAIN_TEXT</jsf>)
+	 * 		.build();
+	 * 	
+	 * 	ObjectMap m = <jk>new</jk> ObjectMap()
+	 * 		.append(<js>"foo"</js>, <js>"bar"</js>);
+	 * 		.append(<js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>,
<js>"true"</js>, <js>"123"</js>});
+	 * 	
+	 * 	<jc>// Produces: "(foo=bar,baz=@(qux,'true','123'))"</jc>
+	 * 	String uon1 = s1.serialize(m)
+	 * 	
+	 * 	<jc>// Produces: "foo=bar,baz=qux,true,123"</jc>
+	 * 	String uon2 = s2.serialize(m)
+	 * </p>
 	 */
 	public static final String UON_paramFormat = PREFIX + "paramFormat.s";
 
@@ -220,7 +270,7 @@ public class UonSerializer extends WriterSerializer {
 	//-------------------------------------------------------------------------------------------------------------------
 
 	/**
-	 * Equivalent to <code><jk>new</jk> UonSerializerBuilder().ws().build();</code>.
+	 * Equivalent to <code>UonSerializer.<jsm>create</jsm>().ws().build();</code>.
 	 */
 	public static class Readable extends UonSerializer {
 
@@ -235,7 +285,7 @@ public class UonSerializer extends WriterSerializer {
 	}
 
 	/**
-	 * Equivalent to <code><jk>new</jk> UonSerializerBuilder().encoding().build();</code>.
+	 * Equivalent to <code>UonSerializer.<jsm>create</jsm>().encoding().build();</code>.
 	 */
 	public static class Encoding extends UonSerializer {
 
@@ -330,15 +380,6 @@ public class UonSerializer extends WriterSerializer {
 		return new UonSerializerSession(this, null, args);
 	}
 	
-	/**
-	 * Returns the value of the {@link UonSerializer#UON_paramFormat} setting.
-	 *
-	 * @return The value of the {@link UonSerializer#UON_paramFormat} setting.
-	 */
-	public ParamFormat getParamFormat() {
-		return paramFormat;
-	}
-	
 	@Override /* Context */
 	public ObjectMap asMap() {
 		return super.asMap()

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializer.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializer.java
index 6482448..2c669b8 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializer.java
@@ -136,22 +136,7 @@ public class UrlEncodingSerializer extends UonSerializer {
 	 * <h5 class='section'>Description:</h5>
 	 * <p>
 	 * If <jk>false</jk>, serializing the array <code>[1,2,3]</code>
results in <code>?key=$a(1,2,3)</code>.
-	 * If <jk>true</jk>, serializing the same array results in <code>?key=1&amp;key=2&amp;key=3</code>.
-	 *
-	 * <p>
-	 * Example:
-	 * <p class='bcode'>
-	 * 	<jk>public class</jk> A {
-	 * 		<jk>public</jk> String[] f1 = {<js>"a"</js>,<js>"b"</js>};
-	 * 		<jk>public</jk> List&lt;String&gt; f2 = <jk>new</jk>
LinkedList&lt;String&gt;(Arrays.<jsm>asList</jsm>(<jk>new</jk>
String[]{<js>"c"</js>,<js>"d"</js>}));
-	 * 	}
-	 *
-	 * 	UrlEncodingSerializer s1 = UrlEncodingSerializer.<jsf>DEFAULT</jsf>;
-	 * 	UrlEncodingSerializer s2 = <jk>new</jk> UrlEncodingSerializerBuilder().expandedParams(<jk>true</jk>).build();
-	 *
-	 * 	String ss1 = s1.serialize(<jk>new</jk> A()); <jc>// Produces "f1=(a,b)&amp;f2=(c,d)"</jc>
-	 * 	String ss2 = s2.serialize(<jk>new</jk> A()); <jc>// Produces "f1=a&amp;f1=b&amp;f2=c&amp;f2=d"</jc>
-	 * </p>
+	 * <br>If <jk>true</jk>, serializing the same array results in <code>?key=1&amp;key=2&amp;key=3</code>.
 	 *
 	 * <p>
 	 * This option only applies to beans.
@@ -162,6 +147,28 @@ public class UrlEncodingSerializer extends UonSerializer {
 	 * 		as bean property types instead of arrays since arrays have to be recreated from scratch
every time a value
 	 * 		is added to it.
 	 * </ul>
+	 * 
+	 * <h5 class='section'>Example:</h5>
+	 * <p class='bcode'>
+	 * 	<jc>// A sample bean.</jc>
+	 * 	<jk>public class</jk> A {
+	 * 		<jk>public</jk> String[] f1 = {<js>"a"</js>,<js>"b"</js>};
+	 * 		<jk>public</jk> List&lt;String&gt; f2 = Arrays.<jsm>asList</jsm>(<jk>new</jk>
String[]{<js>"c"</js>,<js>"d"</js>});
+	 * 	}
+	 *
+	 * 	<jc>// Normal serializer.</jc>
+	 * 	WriterSerializer s1 = UrlEncodingSerializer.<jsf>DEFAULT</jsf>;
+	 * 	
+	 * 	<jc>// Expanded-params serializer.</jc>
+	 * 	WriterSerializer s2 = UrlEncodingSerializer.<jsm>create</jsm>().expandedParams().build();
+	 *	
+	 *	<jc>// Produces "f1=(a,b)&amp;f2=(c,d)"</jc>
+	 * 	String ss1 = s1.serialize(<jk>new</jk> A()); 
+	 * 
+	 * 	<jc>// Produces "f1=a&amp;f1=b&amp;f2=c&amp;f2=d"</jc>
+	 * 	String ss2 = s2.serialize(<jk>new</jk> A()); <jc>
+	 * </p>
+	 *
 	 */
 	public static final String URLENC_expandedParams = PREFIX + "expandedParams.b";
 	
@@ -188,7 +195,7 @@ public class UrlEncodingSerializer extends UonSerializer {
 	//-------------------------------------------------------------------------------------------------------------------
 
 	/**
-	 * Equivalent to <code><jk>new</jk> UrlEncodingSerializerBuilder().expandedParams(<jk>true</jk>).build();</code>.
+	 * Equivalent to <code>UrlEncodingSerializer.<jsm>create</jsm>().expandedParams().build();</code>.
 	 */
 	public static class Expanded extends UrlEncodingSerializer {
 
@@ -203,7 +210,7 @@ public class UrlEncodingSerializer extends UonSerializer {
 	}
 
 	/**
-	 * Equivalent to <code><jk>new</jk> UrlEncodingSerializerBuilder().useWhitespace(<jk>true</jk>).build();</code>.
+	 * Equivalent to <code>UrlEncodingSerializer.<jsm>create</jsm>().useWhitespace().build();</code>.
 	 */
 	public static class Readable extends UrlEncodingSerializer {
 
@@ -218,7 +225,7 @@ public class UrlEncodingSerializer extends UonSerializer {
 	}
 
 	/**
-	 * Equivalent to <code><jk>new</jk> UrlEncodingSerializerBuilder().plainTextParts().build();</code>.
+	 * Equivalent to <code>UrlEncodingSerializer.<jsm>create</jsm>().plainTextParts().build();</code>.
 	 */
 	public static class PlainText extends UrlEncodingSerializer {
 

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializerBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializerBuilder.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializerBuilder.java
index 0501ed3..20bcc68 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializerBuilder.java
@@ -57,7 +57,7 @@ public class UrlEncodingSerializerBuilder extends UonSerializerBuilder {
 	 *
 	 * <p>
 	 * If <jk>false</jk>, serializing the array <code>[1,2,3]</code>
results in <code>?key=$a(1,2,3)</code>.
-	 * If <jk>true</jk>, serializing the same array results in <code>?key=1&amp;key=2&amp;key=3</code>.
+	 * <br>If <jk>true</jk>, serializing the same array results in <code>?key=1&amp;key=2&amp;key=3</code>.
 	 *
 	 * <h5 class='section'>See Also:</h5>
 	 * <ul>

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/yaml/proto/YamlSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/yaml/proto/YamlSerializer.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/yaml/proto/YamlSerializer.java
index e9e63fe..8484cde 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/yaml/proto/YamlSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/yaml/proto/YamlSerializer.java
@@ -67,7 +67,7 @@ import org.apache.juneau.serializer.*;
  * 	String json = JsonSerializer.<jsf>DEFAULT</jsf>.serialize(someObject);
  *
  * 	<jc>// Create a custom serializer for lax syntax using single quote characters</jc>
- * 	JsonSerializer serializer = <jk>new</jk> JsonSerializerBuilder().simple().sq().build();
+ * 	JsonSerializer serializer = JsonSerializer.<jsm>create</jsm>().simple().sq().build();
  *
  * 	<jc>// Clone an existing serializer and modify it to use single-quotes</jc>
  * 	JsonSerializer serializer = JsonSerializer.<jsf>DEFAULT</jsf>.builder().sq().build();

http://git-wip-us.apache.org/repos/asf/juneau/blob/d7562f07/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java
----------------------------------------------------------------------
diff --git a/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java
b/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java
index 30ff8c6..ec38f8f 100644
--- a/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java
+++ b/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java
@@ -430,7 +430,7 @@ public class RestClient extends BeanContext {
 	 * 
 	 *
 	 * <p>
-	 * Shortcut for calling <code><jk>new</jk> RestClientBuilder().serializer(s).parser(p);</code>
+	 * Shortcut for calling <code>RestClient.<jsm>create</jsm>().serializer(s).parser(p);</code>
 	 *
 	 * @param s The serializer class to use for output.
 	 * @param p The parser class to use for input.
@@ -909,18 +909,21 @@ public class RestClient extends BeanContext {
 	 * 	<jk>public interface</jk> MyInterface3 { ... }
 	 *
 	 * 	<jc>// Resolves to "http://localhost/resturl/myinterface1"</jc>
-	 * 	MyInterface1 i1 = <jk>new</jk> RestClientBuilder()
+	 * 	MyInterface1 i1 = RestClient
+	 * 		.<jsm>create</jsm>()
 	 * 		.build()
 	 * 		.getRemoteableProxy(MyInterface1.<jk>class</jk>);
 	 *
 	 * 	<jc>// Resolves to "http://hostname/resturl/myinterface2"</jc>
-	 * 	MyInterface2 i2 = <jk>new</jk> RestClientBuilder()
+	 * 	MyInterface2 i2 = RestClient
+	 * 		.<jsm>create</jsm>()
 	 * 		.rootUrl(<js>"http://hostname/resturl"</js>)
 	 * 		.build()
 	 * 		.getRemoteableProxy(MyInterface2.<jk>class</jk>);
 	 *
 	 * 	<jc>// Resolves to "http://hostname/resturl/org.apache.foo.MyInterface3"</jc>
-	 * 	MyInterface3 i3 = <jk>new</jk> RestClientBuilder()
+	 * 	MyInterface3 i3 = RestClient
+	 * 		.<jsm>create</jsm>()
 	 * 		.rootUrl(<js>"http://hostname/resturl"</js>)
 	 * 		.build()
 	 * 		.getRemoteableProxy(MyInterface3.<jk>class</jk>);


Mime
View raw message