10000 Doc improvements by jonas · Pull Request #488 · circe/circe · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Doc improvements #488

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Dec 1, 2016
Merged

Doc improvements #488

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
71ab55f
Exclude scalaz package from Scaladoc
jonas Dec 1, 2016
c1e2184
Ignore contributing.md copied from the root
jonas Dec 1, 2016
2769e75
Add a minimal viable Scaladoc root document
jonas Dec 1, 2016
c19331f
Document limitation when decoding numerical values on Scala.js
jonas Dec 1, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,4 @@ target/
.project
.classpath
tmp/
docs/src/main/tut/contributing.md
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks—I keep meaning to open a PR for this but hadn't yet.

4 changes: 3 additions & 1 deletion build.sbt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,8 +132,10 @@ lazy val docSettings = allSettings ++ unidocSettings ++ Seq(
scalacOptions in (ScalaUnidoc, unidoc) ++= Seq(
"-groups",
"-implicits",
"-skip-packages", "scalaz",
"-doc-source-url", scmInfo.value.get.browseUrl + "/tree/master€{FILE_PATH}.scala",
"-sourcepath", baseDirectory.in(LocalRootProject).value.getAbsolutePath
"-sourcepath", baseDirectory.in(LocalRootProject).value.getAbsolutePath,
"-doc-root-content", (resourceDirectory.in(Compile).value / "rootdoc.txt").getAbsolutePath
),
git.remoteRepo := "git@github.com:circe/circe.git",
unidocProjectFilter in (ScalaUnidoc, unidoc) :=
Expand Down
1 change: 1 addition & 0 deletions docs/src/main/resources/microsite/includes/references.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
[jawn]: https://github.com/non/jawn
[jsactor]: https://github.com/codemettle/jsactor
[json-schema]: http://json-schema.org/
[json.parse]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
[jsonpath]: https://github.com/circe/circe/blob/master/optics/src/main/scala/io/circe/optics/JsonPath.scala
[jwt]: https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32
[jwt-circe]: http://pauldijou.fr/jwt-scala/samples/jwt-circe/
Expand Down
18 changes: 18 additions & 0 deletions docs/src/main/resources/rootdoc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
This is the Scaladoc for [[http://circe.io circe]], a JSON library for Scala
and Scala.js.

The library is divided into several modules each focusing on various aspects
of working with JSON as well as codecs for 3rd party libraries. Noteworthy
modules are:

- The [[io.circe core]] module, which is focused on the JSON AST, zippers,
and codecs.
- The [[io.circe.generic generic]] module for automatic and semi-automatic
[[https://circe.github.io/circe/codec.html derivation]] of encoders and
decoders.
- The [[io.circe.optics optics]] module providing an alternative way to
traverse JSON documents using lenses.
- The [[io.circe.shapes shapes]] module for working with Shapeless.

Please refer to the [[https://circe.github.io/circe/ documentation]] for a
detailed introduction to circe.
14 changes: 13 additions & 1 deletion docs/src/main/tut/parsing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ position: 1

# Parsing JSON

Circe includes a parsing module, which is a wrapper around the [Jawn][jawn] JSON parser.
Circe includes a parsing module, which on the JVM is a wrapper around the [Jawn][jawn] JSON parser and for JavaScript uses the built-in [`JSON.parse`][json.parse].

Parsing is not part of the `circe-core` module, so you will need to include a dependency on the `circe-parser` module in your build:

Expand Down Expand Up @@ -60,4 +60,16 @@ import cats.syntax.either._
val json: Json = parse(rawJson).getOrElse(Json.Null)
```

## Warnings and known issues

When using the Scala.js version of circe, numerical values like `Long` may [lose
precision][#393] when decoded. For example `decode[Long]("767946224062369796")`
will return `Right(767946224062369792L)`. This is not a limitation of how
Scala.js represents `scala.Long`s nor circe's decoders for numerical values but
due to [`JSON.parse`][json.parse] converting numerical values to JavaScript
numbers. If precision is required consider representing numerical values as
strings and convert them to their final value via the JSON AST.

[#393]: https://github.com/circe/circe/issues/393

{% include references.md %}
0