diff --git a/NEWS.md b/NEWS.md
index a333a4b..9604f96 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -5,10 +5,12 @@
  - Update circe to version [0.9.0](https://github.com/circe/circe/releases/tag/v0.9.0).
  - Update to [config 1.3.2].
  - Update Scala to 2.11.12.
+ - Document limitations regarding numerical types. [#7]
  - Configure MiMa. [#4], [#8]
  - Build using sbt 1.0. [#9]
 
  [#4]: https://github.com/circe/circe-config/issues/4
+ [#7]: https://github.com/circe/circe-config/issues/7
  [#8]: https://github.com/circe/circe-config/pull/8
  [#9]: https://github.com/circe/circe-config/pull/9
  [config 1.3.2]: https://github.com/lightbend/config/blob/master/NEWS.md#132-october-6-2017
diff --git a/src/main/scala/io.circe.config/package.scala b/src/main/scala/io.circe.config/package.scala
index a796ef3..f5807bd 100644
--- a/src/main/scala/io.circe.config/package.scala
+++ b/src/main/scala/io.circe.config/package.scala
@@ -22,6 +22,15 @@ import scala.collection.JavaConverters._
  * circe-config: A [[https://github.com/lightbend/config Typesafe config]]
  * wrapper powered by [[io.circe circe]].
  *
+ * @note '''Limitations for numerical types''':
+ * Typesafe config uses Java's int, long and double types to represent numbers.
+ * In some cases, double values may be represented internally as long after a
+ * roundtrip since the [[https://github.com/lightbend/config/blob/master/HOCON.md HOCON]]
+ * formatting is not stable. Also, precision may be lost when converting from
+ * circe's [[io.circe.JsonNumber JsonNumber]] to Typesafe config's number
+ * representation (as can be seen in the
+ * [[https://github.com/circe/circe-config/blob/master/src/test/scala/io.circe.config/CirceConfigLaws.scala#L16-L40 test for the printer laws]]).
+ *
  * @example
  * {{{
  * scala> import com.typesafe.config.ConfigFactory