5 files changed, 83 insertions, 68 deletions
diff --git a/docs/src/wiki-deprecated/chisel3-vs-chisel2.md b/docs/src/appendix/chisel3-vs-chisel2.md
index bfd20348..bfd20348 100644
--- a/docs/src/wiki-deprecated/chisel3-vs-chisel2.md
+++ b/docs/src/appendix/chisel3-vs-chisel2.md
diff --git a/docs/src/wiki-deprecated/experimental-features.md b/docs/src/appendix/experimental-features.md
index d36b2946..ba1a028d 100644
--- a/docs/src/wiki-deprecated/experimental-features.md
+++ b/docs/src/appendix/experimental-features.md
@@ -12,7 +12,7 @@ are supported. Chisel allows both the width and binary point to be inferred by t
 circuit descriptions. See [FixedPointSpec](https://github.com/freechipsproject/chisel3/tree/master/src/test/scala/chiselTests/FixedPointSpec.scala)
 
 ### Module Variants
-The standard Chisel *Module* requires a ```val io = IO(...)```, the experimental package introduces several
+The standard Chisel *Module* requires a `val io = IO(...)`, the experimental package introduces several
 new ways of defining Modules
 - BaseModule: no contents, instantiable
 - BlackBox extends BaseModule
@@ -23,45 +23,64 @@ new ways of defining Modules
 
 ### Bundle Literals
 
-Chisel 3.2 introduces an experimental mechanism for Bundle literals in #820, but this feature is largely incomplete and not ready for user code yet. The following is provided as documentation for library writers who want to take a stab at using this mechanism for their library's bundles.
+Bundle literals can be constructed via an experimental import:
+
+```scala mdoc
+import chisel3._
+import chisel3.experimental.BundleLiterals._
 
-```mdoc scala
 class MyBundle extends Bundle {
   val a = UInt(8.W)
   val b = Bool()
+}
 
-  // Bundle literal constructor code, which will be auto-generated using macro annotations in
-  // the future.
-  import chisel3.core.BundleLitBinding
-  import chisel3.internal.firrtl.{ULit, Width}
-
-  // Full bundle literal constructor
-  def Lit(aVal: UInt, bVal: Bool): MyBundle = {
-    val clone = cloneType
-    clone.selfBind(BundleLitBinding(Map(
-      clone.a -> litArgOfBits(aVal),
-      clone.b -> litArgOfBits(bVal)
-    )))
-    clone
-  }
-
-  // Partial bundle literal constructor
-  def Lit(aVal: UInt): MyBundle = {
-    val clone = cloneType
-    clone.selfBind(BundleLitBinding(Map(
-      clone.a -> litArgOfBits(aVal)
-    )))
-    clone
-  }
+class Example extends RawModule {
+  val out = IO(Output(new MyBundle))
+  out := (new MyBundle).Lit(_.a -> 8.U, _.b -> true.B)
 }
 ```
 
-Example usage:
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new Example)
+```
+
+Partial specification is allowed, defaulting any unconnected fields to 0 (regardless of type).
+
+```scala mdoc
+class Example2 extends RawModule {
+  val out = IO(Output(new MyBundle))
+  out := (new MyBundle).Lit(_.b -> true.B)
+}
+```
 
-```scala
-val outsideBundleLit = (new MyBundle).Lit(42.U, true.B)
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new Example2)
 ```
 
+Bundle literals can also be nested arbitrarily.
+
+```scala mdoc
+class ChildBundle extends Bundle {
+  val foo = UInt(8.W)
+}
+
+class ParentBundle extends Bundle {
+  val a = UInt(8.W)
+  val b = new ChildBundle
+}
+
+class Example3 extends RawModule {
+  val out = IO(Output(new ParentBundle))
+  out := (new ParentBundle).Lit(_.a -> 123.U, _.b -> (new ChildBundle).Lit(_.foo -> 42.U))
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new Example3)
+```
+
+Vec literals are not yet supported.
+
 ### Interval Type
 
 **Intervals** are a new experimental numeric type that comprises UInt, SInt and FixedPoint numbers.
diff --git a/docs/src/wiki-deprecated/upgrading-from-scala-2-11.md b/docs/src/appendix/upgrading-from-scala-2-11.md
index 26e2d252..26e2d252 100644
--- a/docs/src/wiki-deprecated/upgrading-from-scala-2-11.md
+++ b/docs/src/appendix/upgrading-from-scala-2-11.md
diff --git a/docs/src/explanations/blackboxes.md b/docs/src/explanations/blackboxes.md
index a8d5fe03..4ecd1ea0 100644
--- a/docs/src/explanations/blackboxes.md
+++ b/docs/src/explanations/blackboxes.md
@@ -9,7 +9,7 @@ for hardware constructs that cannot be described in Chisel and for connecting to
 Modules defined as a `BlackBox` will be instantiated in the generated Verilog, but no code
 will be generated to define the behavior of module.
 
-Unlike Module, `BlackBox` has no implicit clock and reset. 
+Unlike Module, `BlackBox` has no implicit clock and reset.
 `BlackBox`'s clock and reset ports must be explicitly declared and connected to input signals.
 Ports declared in the IO Bundle will be generated with the requested name (ie. no preceding `io_`).
 
@@ -34,7 +34,7 @@ class IBUFDS extends BlackBox(Map("DIFF_TERM" -> "TRUE",
 }
 
 class Top extends Module {
-  val io = IO(new Bundle{})
+  val io = IO(new Bundle {})
   val ibufds = Module(new IBUFDS)
   // connecting one of IBUFDS's input clock ports to Top's clock signal
   ibufds.io.I := clock
@@ -52,12 +52,14 @@ IBUFDS #(.DIFF_TERM("TRUE"), .IOSTANDARD("DEFAULT")) ibufds (
 ```
 
 ### Providing Implementations for Blackboxes
+
 Chisel provides the following ways of delivering the code underlying the blackbox.  Consider the following blackbox that
  adds two real numbers together.  The numbers are represented in chisel3 as 64-bit unsigned integers.
+
 ```scala mdoc:silent:reset
 import chisel3._
 class BlackBoxRealAdd extends BlackBox {
-  val io = IO(new Bundle() {
+  val io = IO(new Bundle {
     val in1 = Input(UInt(64.W))
     val in2 = Input(UInt(64.W))
     val out = Output(UInt(64.W))
@@ -66,6 +68,7 @@ class BlackBoxRealAdd extends BlackBox {
 ```
 
 The implementation is described by the following verilog
+
 ```verilog
 module BlackBoxRealAdd(
     input  [63:0] in1,
@@ -73,39 +76,43 @@ module BlackBoxRealAdd(
     output reg [63:0] out
 );
   always @* begin
-  out <= $realtobits($bitstoreal(in1) + $bitstoreal(in2));
+    out <= $realtobits($bitstoreal(in1) + $bitstoreal(in2));
   end
 endmodule
 ```
 
 ### Blackboxes with Verilog in a Resource File
-In order to deliver the verilog snippet above to the backend simulator, chisel3 provides the following tools based on the chisel/firrtl [annotation system](../explanations/annotations).  Add the trait ```HasBlackBoxResource``` to the declaration, and then call a function in the body to say where the system can find the verilog.  The Module now looks like
-```mdoc scala:silent:reset
+
+In order to deliver the verilog snippet above to the backend simulator, chisel3 provides the following tools based on the chisel/firrtl [annotation system](../explanations/annotations).  Add the trait `HasBlackBoxResource` to the declaration, and then call a function in the body to say where the system can find the verilog.  The Module now looks like
+
+```scala mdoc:silent:reset
+import chisel3._
+import chisel3.util.HasBlackBoxResource
+
 class BlackBoxRealAdd extends BlackBox with HasBlackBoxResource {
-  val io = IO(new Bundle() {
+  val io = IO(new Bundle {
     val in1 = Input(UInt(64.W))
     val in2 = Input(UInt(64.W))
     val out = Output(UInt(64.W))
   })
-  setResource("/real_math.v")
+  addResource("/real_math.v")
 }
 ```
-The verilog snippet above gets put into a resource file names ```real_math.v```.  What is a resource file? It comes from
+
+The verilog snippet above gets put into a resource file names `real_math.v`.  What is a resource file? It comes from
  a java convention of keeping files in a project that are automatically included in library distributions. In a typical
  chisel3 project, see [chisel-template](https://github.com/ucb-bar/chisel-template), this would be a directory in the
- source hierarchy
-```
-src/main/resources/real_math.v
-```
+ source hierarchy: `src/main/resources/real_math.v`.
 
 ### Blackboxes with In-line Verilog
-It is also possible to place this verilog directly in the scala source.  Instead of ```HasBlackBoxResource``` use 
- ```HasBlackBoxInline``` and instead of ```setResource``` use ```setInline```.  The code will look like this.
+It is also possible to place this verilog directly in the scala source.  Instead of `HasBlackBoxResource` use
+ `HasBlackBoxInline` and instead of `setResource` use `setInline`.  The code will look like this.
+
 ```scala mdoc:silent:reset
 import chisel3._
 import chisel3.util.HasBlackBoxInline
 class BlackBoxRealAdd extends BlackBox with HasBlackBoxInline {
-  val io = IO(new Bundle() {
+  val io = IO(new Bundle {
     val in1 = Input(UInt(64.W))
     val in2 = Input(UInt(64.W))
     val out = Output(UInt(64.W))
@@ -123,15 +130,16 @@ class BlackBoxRealAdd extends BlackBox with HasBlackBoxInline {
     """.stripMargin)
 }
 ```
-This technique will copy the inline verilog into the target directory under the name ```BlackBoxRealAdd.v```
+
+This technique will copy the inline verilog into the target directory under the name `BlackBoxRealAdd.v`
 
 ### Under the Hood
 This mechanism of delivering verilog content to the testing backends is implemented via chisel/firrtl annotations. The
-two methods, inline and resource, are two kinds of annotations that are created via the ```setInline``` and
-```setResource``` methods calls.  Those annotations are passed through to the chisel-testers which in turn passes them
+two methods, inline and resource, are two kinds of annotations that are created via the `setInline` and
+`setResource` methods calls.  Those annotations are passed through to the chisel-testers which in turn passes them
 on to firrtl.  The default firrtl verilog compilers have a pass that detects the annotations and moves the files or
 inline test into the build directory.  For each unique file added, the transform adds a line to a file
-black_box_verilog_files.f, this file is added to the command line constructed for verilator or vcs to inform them where
+`black_box_verilog_files.f`, this file is added to the command line constructed for verilator or vcs to inform them where
 to look.
 The [dsptools project](https://github.com/ucb-bar/dsptools) is a good example of using this feature to build a real
 number simulation tester based on black boxes.
@@ -144,4 +152,4 @@ construct scala implementations of the black boxes.  The scala implementation co
 passed down to the interpreter by the execution harness.  The interpreter is a scala simulation tester.  Once again the
 dsptools project uses this mechanism and is a good place to look at it.
 > It is planned that the BlackBoxFactory will be replaced by integration with the annotation based blackbox methods
->stuff soon.
+> stuff soon.
diff --git a/docs/src/explanations/bundles-and-vecs.md b/docs/src/explanations/bundles-and-vecs.md
index dcac31cd..bac9393a 100644
--- a/docs/src/explanations/bundles-and-vecs.md
+++ b/docs/src/explanations/bundles-and-vecs.md
@@ -3,14 +3,12 @@ layout: docs
 title:  "Bundles and Vecs"
 section: "chisel3"
 ---
-```
-
-```
 
 `Bundle` and `Vec` are classes that allow the user to expand the set of Chisel datatypes with aggregates of other types.
 
 Bundles group together several named fields of potentially different types into a coherent unit, much like a `struct` in
 C. Users define their own bundles by defining a class as a subclass of `Bundle`.
+
 ```scala mdoc:silent
 import chisel3._
 class MyFloat extends Bundle {
@@ -25,24 +23,12 @@ class ModuleWithFloatWire extends RawModule {
 }
 ```
 
-> Currently, there is no way to create a bundle literal like ```8.U``` for ```UInt```s. Therefore, in order to create
->literals for bundles, we must declare a [[wire|Combinational-Circuits#wires]] of that bundle type, and then assign
->values to it. We are working on a way to declare bundle literals without requiring the creation of a Wire node and
->assigning to it.
+You can create literal Bundles using the experimental [Bundle Literals](../appendix/experimental-features#bundle-literals) feature.
 
-```scala mdoc:silent
-class ModuleWithFloatConstant extends RawModule {
-  // Floating point constant.
-  val floatConst = Wire(new MyFloat)
-  floatConst.sign := true.B
-  floatConst.exponent := 10.U
-  floatConst.significand := 128.U
-}
-```
-
-A Scala convention is to capitalize the name of new classes and we suggest you follow that convention in Chisel too.
+Scala convention is to name classes using UpperCamelCase, and we suggest you follow that convention in your Chisel code.
 
 Vecs create an indexable vector of elements, and are constructed as follows:
+
 ```scala mdoc:silent
 class ModuleWithVec extends RawModule {
   // Vector of 5 23-bit signed integers.
@@ -63,6 +49,7 @@ superclass, `Data`.  Every object that ultimately inherits from
 
 Bundles and Vecs can be arbitrarily nested to build complex data
 structures:
+
 ```scala mdoc:silent
 class BigBundle extends Bundle {
  // Vector of 5 23-bit signed integers.
@@ -152,6 +139,7 @@ Note that in the vast majority of cases, **this is not required** as Chisel can
 automatically.
 
 Here is an example of a parametrized bundle (`ExampleBundle`) that features a custom `cloneType`.
+
 ```scala mdoc:silent
 class ExampleBundle(a: Int, b: Int) extends Bundle {
     val foo = UInt(a.W)