Merge pull request #251 from mgold/dev2

Convert JavaScript and JSON docs.

libraries/JavaScript.elm

@@ -1,6 +1,22 @@
 
 module JavaScript where
 
+{-|This library does basic conversions between Elm and JS values. This allows
+the internal data structures of Elm to change and improve with no impact on JS
+integration.
+
+# Javascript to Elm
+@docs toString, toInt, toFloat, toBool, toList
+
+# JavaScript from Elm
+@docs fromString, fromInt, fromFloat, fromBool fromList
+
+-}
+{-
+# DOM Nodes and Elements
+@docs toElement, fromElement
+-}
+
 import Native.JavaScript
 import open Basics
 
@@ -45,12 +61,12 @@ fromString : String -> JSString
 fromString = Native.JavaScript.fromString
 
 {--
--- Turn an `Element` into a plain old DOM node.
+{-| Turn an `Element` into a DOM node. -}
 fromElement : Element -> JSDomNode
 fromElement = Native.JavaScript.fromElement
 
--- Turn a DOM node into an `Element`. You can resize the node
--- using the normal `width` and `height` functions.
+{-| Turn a DOM node into an `Element`. You can resize the node
+using the normal `width` and `height` functions. -}
 toElement : Int -> Int -> JSDomNode -> Element
 toElement = Native.JavaScript.toElement
---}
+--}

libraries/Json.elm

@@ -1,8 +1,19 @@
 
--- TOOD: Evan please review texts
-
 module Json where
 
+{-| Library for working with [JSON](https://en.wikipedia.org/wiki/JSON) values.
+
+# Strings
+@docs fromString, toString
+
+# JS Strings
+@docs fromJSString, toJSString
+
+# JS Objects
+@docs fromJSObject, toJSObject
+
+-}
+
 import open Basics
 import Dict
 import Maybe (Maybe)
@@ -10,9 +21,9 @@ import JavaScript as JS
 import Native.Json
 import JavaScript (JSObject, JSString)
 
--- This datatype can represent all valid values that can be held in a JSON
--- object. In Elm, a proper JSON object is represented as a (Dict String JsonValue)
--- which is a mapping from strings to Json Values.
+{-| This datatype can represent all valid values that can be held in a JSON
+object. In Elm, a proper JSON object is represented as a (Dict String JsonValue)
+which is a mapping from strings to Json Values. -}
 data JsonValue
     = String String
     | Number Float
@@ -24,42 +35,43 @@ data JsonValue
 
 -- String Converters
 
--- Convert a `JsonValue` into a prettified string.
--- The first argument is a separator token (e.g. \" \", \"\\n\", etc.) that will
--- be used for indentation in the prettified string version of the JSON.
+{-| Convert a `JsonValue` into a prettified string.
+The first argument is a separator token (e.g. \" \", \"\\n\", etc.) that will
+be used for indentation in the prettified string version of the JSON. -}
 toString : String -> JsonValue -> String
 toString sep v = JS.toString (Native.Json.toJSString sep v)
 
--- Convert a proper JSON object into a JavaScript string.
--- Note that the type JSString seen here is not the same as the type constructor
--- JsonString used elsewhere in this module.
+{-| Convert a proper JSON object into a JavaScript string.
+Note that the type JSString seen here is not the same as the type constructor
+JsonString used elsewhere in this module. -}
 toJSString : String -> JsonValue -> JSString
 toJSString = Native.Json.toJSString
 
--- Parse a string representation of a proper JSON object into
--- its Elm representation.
+{-| Parse a string representation of a proper JSON object into
+its Elm representation. -}
 fromString : String -> Maybe JsonValue
 fromString s = Native.Json.fromJSString (JS.fromString s)
 
--- Parse a JavaScript string representation of a proper JSON object into
--- its Elm representation.
+{-| Parse a JavaScript string representation of a proper JSON object into
+its Elm representation. -}
 fromJSString : JSString -> Maybe JsonValue
 fromJSString = Native.Json.fromJSString
 
--- Convert a JS object into a `JsonValue`.
+{-| Convert a JS object into a `JsonValue`. -}
 fromJSObject : JSObject -> JsonValue
 fromJSObject = Native.Json.fromJSObject
 
--- Convert a `JsonValue` into a `JSObject`. Paired with the
--- [`JavaScript.Experimental` library](/docs/JavaScript/Experimental.elm),
--- This lets you convert strings into Elm records:
---
---       import JavaScript.Experimental as JS
---
---       stringToRecord str =
---           case fromString str of
---             Just jsonValue -> Just (JS.toRecord (toJSObject jsonValue))
---             Nothing -> Nothing
+{-| Convert a `JsonValue` into a `JSObject`. Paired with the
+[`JavaScript.Experimental` library](/docs/JavaScript/Experimental.elm),
+This lets you convert strings into Elm records:
+
+       import JavaScript.Experimental as JS
+
+       stringToRecord str =
+           case fromString str of
+             Just jsonValue -> Just (JS.toRecord (toJSObject jsonValue))
+             Nothing -> Nothing
+-}
 toJSObject : JsonValue -> JSObject
 toJSObject = Native.Json.toJSObject
 
@@ -83,8 +95,8 @@ toJSObject = Native.Json.toJSObject
 
  -- Extract Elm values from dictionaries of Json values
 
- -- Find a value in a Json Object using the passed get function. If the key is
- -- not found, this returns the given default/base value.
+ {-| Find a value in a Json Object using the passed get function. If the key is
+ not found, this returns the given default/base value. -}
  find get base =
    let f key dict =
            case Dict.lookup key dict of
@@ -92,28 +104,28 @@ toJSObject = Native.Json.toJSObject
              Just v  -> get v
    in  f
 
- -- Find a string value in an Elm Json object. If the key is not found or the
- -- value found is not a string, this returns the empty string.
+ {-| Find a string value in an Elm Json object. If the key is not found or the
+ value found is not a string, this returns the empty string. -}
  findString : String -> Object -> String
  findString = find string ""
 
- -- Find a number value in an Elm Json object. If the key is not found or the
- -- value found is not a number, this returns 0
+ {-| Find a number value in an Elm Json object. If the key is not found or the
+ value found is not a number, this returns 0 -}
  findNumber : String -> Object -> Float
  findNumber = find number 0
 
- -- Find a boolean value in an Elm Json object. If the key is not found or the
- -- value found is not a boolean, this returns the False.
+ {-| Find a boolean value in an Elm Json object. If the key is not found or the
+ value found is not a boolean, this returns the False. -}
  findBoolean : String -> Object -> Bool
  findBoolean = find boolean False
 
- -- Find an array value in an Elm Json object. If the key is not found or the
- -- value found is not an array, this returns an empty list.
+ {-| Find an array value in an Elm Json object. If the key is not found or the
+ value found is not an array, this returns an empty list. -}
  findArray : String -> Object -> [JsonValue]
  findArray = find array []
 
- -- Find an object value in an Elm Json object. If the key is not found or the
- -- value found is not an object, this returns an empty object.
+ {-| Find an object value in an Elm Json object. If the key is not found or the
+ value found is not an object, this returns an empty object. -}
  findObject : String -> Object -> Object
  findObject = find object Dict.empty
- --}
+ --}