diff --git a/doc/docs.md b/doc/docs.md
index f0f0e3ce3f..ad01bcfc55 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -383,6 +383,47 @@ s := r'hello\nworld'
 println(s) // "hello\nworld"
 ```
 
+### Numbers
+
+```v
+a := 123
+```
+This will assign the value of 123 to `a`. By default `a` will have the
+type of `int`.
+
+You can also use hexadecimal notation for integer literals:
+```v
+a := 0x7B
+```
+... or binary notation for integer literals:
+```v
+a := 0b01111011
+```
+... or octal notation for specifying integer literals:
+```v
+a := 0o173
+```
+
+All of these will assign the same value 123 to `a`. `a` will have the
+type of `int` no matter what notation you have used for the integer literal.
+
+
+If you want a different type of integer, you can use casting:
+```v
+a := i64(123)
+b := byte(42)
+c := i16(12345)
+```
+
+Assigning floating point numbers works the same way:
+```v
+f := 1.0
+f1 := f64(3.14)
+f2 := f32(3.14)
+```
+If you do not specify the type explicitly, by default float literals 
+will have the type of `f64`.
+
 ### Arrays
 
 ```v
diff --git a/vlib/builtin/int_test.v b/vlib/builtin/int_test.v
index 0368dd65e1..94cc942d7d 100644
--- a/vlib/builtin/int_test.v
+++ b/vlib/builtin/int_test.v
@@ -104,6 +104,25 @@ fn test_hex() {
 	assert b1.hex() == 'ffffffff'
 }
 
+fn test_bin() {
+	x1 := 0b10
+	assert x1 == 2
+	x2 := 0b10101010
+	assert x2 == 0xAA
+	x3 := -0b0000001
+	assert x3 == -1
+	x4 := 0b11111111
+	assert x4 == 255
+	x5 := byte(0b11111111)
+	assert x5 == 255
+	x6 := char(0b11111111)
+	assert int(x6) == -1
+	x7 := 0b0
+	assert x7 == 0
+	x8 := -0b0
+	assert x8 == 0
+}
+
 fn test_oct() {
 	x1 := 0o12
 	assert x1 == 10