Sebastián Magrí avatar Sebastián Magrí committed 40cb57c

Fix and improve haddock documentation for the project

Comments (0)

Files changed (9)

src/Network/SoundCloud.hs

    Maintainer:  Sebastián Ramírez Magrí <sebasmagri@gmail.com>
    Stability:   experimental
 
-   The 'Network.SoundCloud' module provides functions and types to access
+   The @Network.SoundCloud@ module provides functions and types to access
    the soundcloud.com public API.
+
+   /Resource Modules/
+
+   The library is composed by a set of modules implementing datatypes and
+   functions for the resources available through the API. Namely,
+
+     * "Network.SoundCloud.App"
+
+     * "Network.SoundCloud.Comment"
+
+     * "Network.SoundCloud.Group"
+
+     * "Network.SoundCloud.MiniUser"
+
+     * "Network.SoundCloud.Set"
+
+     * "Network.SoundCloud.Track"
+
+     * "Network.SoundCloud.User"
+
+   Every resource module defines at least a @JSON@ record and the @getJSON@ and @decodeJSON@ functions.
+
+   /Base Modules/
+
+   The base modules provide values and functions that are to be used by the rest of the modules in the
+   library. The base modules are,
+
+     * "Network.SoundCloud.Const"
+
+     * "Network.SoundCloud.Util"
+
+   /API Documentation/
+
+   Documentation of the SoundCloud's API can be found at <http://developers.soundcloud.com/docs/>
 -}
 
 module Network.SoundCloud (
   scResolve,
   scResourceType,
   scResourceShowInfo,
-  scShowInfo,
+  scShowInfo
   ) where
 
 import Network.SoundCloud.Util (scGet, scFetch, scResolve, scResourceType)

src/Network/SoundCloud/App.hs

    Maintainer:  Sebastián Ramírez Magrí <sebasmagri@gmail.com>
    Stability:   experimental
 
-   Represents SoundCloud applications as found at http://soundcloud.com/apps
+   Represents SoundCloud applications as found at <http://soundcloud.com/apps>
 -}
 
 module Network.SoundCloud.App where
 
 import Network.SoundCloud.Util (scGet, scResolve)
 
--- | JSON representation of applications as described
--- in http://developers.soundcloud.com/docs/api/apps
+-- | JSON representation of applications
 data JSON = JSON { id                     :: Int
                  , permalink_url          :: String
                  , external_url           :: String
 instance ToJSON   JSON
 
 -- | Decode a valid JSON string into an application
--- JSON record
+-- 'JSON' record
 decodeJSON :: String -> Maybe JSON
 decodeJSON dat = decode (BSL.pack dat) :: Maybe JSON
 
 
--- | Get an application JSON record given a public app URL
--- as in http://soundcloud.com/apps/app_name
+-- | Get an application 'JSON' record given a public app URL
+-- as in <http://soundcloud.com/apps/app_name>
 getJSON :: String -> IO (Maybe JSON)
 getJSON url =
     do tUrl <- scResolve url

src/Network/SoundCloud/Comment.hs

 instance ToJSON   JSON
 
 -- | Decode a comment's valid JSON string into
--- a comment's JSON record
+-- a comment's 'JSON' record
 decodeJSON :: String -> Maybe JSON
 decodeJSON dat = decode (BSL.pack dat) :: Maybe JSON
 

src/Network/SoundCloud/Group.hs

 instance FromJSON JSON
 instance ToJSON   JSON
 
--- | Decode a group's valid JSON string into a record
+-- | Decode a group's valid JSON string into a 'JSON' record
 decodeJSON :: String -> Maybe JSON
 decodeJSON dat = decode (BSL.pack dat) :: Maybe JSON
 

src/Network/SoundCloud/MiniUser.hs

 instance FromJSON JSON
 instance ToJSON   JSON
 
--- | Decode a JSON record from a valid miniuser
+-- | Decode a 'JSON' record from a valid miniuser
 -- JSON string
 decodeJSON :: String -> Maybe JSON
 decodeJSON dat = decode (BSL.pack dat) :: Maybe JSON

src/Network/SoundCloud/Set.hs

 instance FromJSON JSON
 instance ToJSON   JSON
 
--- | Decode a JSON record from a valid set
+-- | Decode a 'JSON' record from a valid set
 -- JSON string
 decodeJSON :: String -> Maybe JSON
 decodeJSON dat = decode (BSL.pack dat) :: Maybe JSON
 
--- | Get a set JSON record given it's public URL
--- as in http://soundcloud.com/artist/set_title
+-- | Get a set 'JSON' record given it's public URL
+-- as in <http://soundcloud.com/artist/set_title>
 getJSON :: String -> IO (Maybe JSON)
 getJSON url =
     do tUrl <- scResolve url

src/Network/SoundCloud/Track.hs

    Maintainer:  Sebastián Ramírez Magrí <sebasmagri@gmail.com>
    Stability:   experimental
 
-   Implements tracks and related types and functions
+   Implements tracks related types and functions
 -}
 
 module Network.SoundCloud.Track where
 instance FromJSON DownloadJSON
 instance ToJSON   DownloadJSON
 
--- | Decode a JSON record from a track valid JSON string
+-- | Decode a 'JSON' record from a track valid JSON string
 decodeJSON :: String -> Maybe JSON
 decodeJSON dat = decode (BSL.pack dat) :: Maybe JSON
 
--- | Get a JSON record given a track URL
--- as in http://soundcloud.com/artist/track_title
+-- | Get a 'JSON' record given a track URL
+-- as in <http://soundcloud.com/artist/track_title>
 getJSON :: String -> IO (Maybe JSON)
 getJSON url =
     do tUrl <- scResolve url
          Nothing -> return Nothing
          Just d  -> return $ decodeJSON d
 
--- | Decode a DownloadJSON record out of a track's JSON
+-- | Decode a 'DownloadJSON' record out of a track's JSON
 decodeDownloadJSON :: String -> Maybe DownloadJSON
 decodeDownloadJSON dat = decode (BSL.pack dat) :: Maybe DownloadJSON
 
--- | Decode a comment JSON list given a track id
+-- | Decode a "Network.SoundCloud.Comment" @JSON@ list given a track id
 decodeComments :: String -> Maybe [Comment.JSON]
 decodeComments dat = decode (BSL.pack dat) :: Maybe [Comment.JSON]
 
--- | Given the track id, get its comments as a list of Comment.JSON
+-- | Given the track id, get its comments as a list of "Network.SoundCloud.Comment" @JSON@
 getComments :: Int -> IO (Maybe [Comment.JSON])
 getComments trackId =
     do let url = tracksURL ++ "/" ++ show trackId ++ "/comments.json?client_id=" ++ clientId

src/Network/SoundCloud/User.hs

    Maintainer:  Sebastián Ramírez Magrí <sebasmagri@gmail.com>
    Stability:   experimental
 
-   Implements tracks and related types and functions
+   Implements users related types and functions
 -}
 
 module Network.SoundCloud.User where
 instance FromJSON JSON
 instance ToJSON   JSON
 
--- | Decode a JSON record out of a user's valid JSON string
+-- | Decode a 'JSON' record out of a user's valid JSON string
 decodeJSON :: String -> Maybe JSON
 decodeJSON dat = decode (BSL.pack dat) :: Maybe JSON
 
--- | Get a JSON record given an user URL
--- as in http://soundcloud.com/artist
+-- | Get a 'JSON' record given an user URL
+-- as in <http://soundcloud.com/artist>
 getJSON :: String -> IO (Maybe JSON)
 getJSON url =
     do tUrl <- scResolve url

src/Network/SoundCloud/Util.hs

 
 import Network.SoundCloud.Const
 
--- | Issue a GET request to an URL and returns
--- the response body as a String or Nothing on failure.
--- If 'followRedirections' is set to True, new requests
--- will be made on 3XX response codes to the Location of
--- the response.
+-- | Issue a @GET@ request to an URL given as first parameter
+-- and returns the response body as a 'String' or 'Nothing'
+-- on failure.
+--
+-- If the second argument is set to 'True', and a @3XX@
+-- response code is found, a new request will be made
+-- to the @Location@ header of the response.
 scGet :: String -> Bool -> IO (Maybe String)
 scGet url followRedirections =
     do res <- simpleHTTP $ getRequest url
                          else return $ Just uri
                _ -> return Nothing
 
--- | Issue a GET request to 'dUrl' and save the response body
--- to a file in the path indicated by the 'out' parameter
+-- | Given an URL as a first parameter, and a path as a second,
+-- issue a @GET@ request to the @URL@ and save the response body
+-- to a file at @path@.
 scFetch :: String -> String -> IO ()
 scFetch dUrl out =
     do contents <- scGet dUrl True
 
 -- | Given an arbitrary resource URL, returns the type of the
 -- resource.
+--
 -- The response can be one of:
---   "track"
---   "user"
---   "set"
---   "group"
---   "comment"
---   "app"
---   "nothing"
+--
+--   * @track@
+--
+--   * @user@
+--
+--   * @set@
+--
+--   * @group@
+--
+--   * @comment@
+--
+--   * @app@
+--
+--   * @nothing@
 scResourceType :: String -> String
 scResourceType url | tracksURL    `isPrefixOf` url      = "track"
                    | usersURL     `isPrefixOf` url      = "user"
 -}
 -- | Get the API url of a resource given its public URL.
 -- In example, for a public URL like:
---     http://soundcloud.com/user/track
+--
+--     <http://soundcloud.com/user/track>
+--
 -- It returns the API URL:
---     http://api.soundcloud.com/tracks/<track_id>.json?client_id=<foo>
+--
+--     <http://api.soundcloud.com/tracks/track_id.json?client_id=foo>
 scResolve :: String -> IO String
 scResolve url =
     do dat <- scGet resolveUrl False
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.