@@ -168,6 +168,10 @@ import Data.Swagger.Internal
168168-- :}
169169-- "{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/#/definitions/User\"},\"description\":\"\"}},\"produces\":[\"application/json\"]}}}"
170170--
171+-- In the snippet above we declare API paths with a single path @/user@ providing method @GET@
172+-- which produces @application/json@ output and should respond with code @200@ and body specified
173+-- by schema @User@ (which should be defined in @definitions@ property of swagger specification).
174+--
171175-- Since @'ParamSchema'@ is basically the /base schema specification/, a special
172176-- @'HasParamSchema'@ class has been introduced to generalize @'ParamSchema'@ lenses
173177-- and allow them to be used by any type that has a @'ParamSchema'@:
@@ -182,8 +186,18 @@ import Data.Swagger.Internal
182186
183187-- $schema
184188--
185−-- This library provides two classes for schema encoding.
186−-- Both these classes provide means to encode _types_ as Swagger _schemas_.
189+-- @'ParamSchema'@ and @'Schema'@ are the two core types for data model specification.
190+--
191+-- @'ParamSchema' t@ specifies all the common properties, available for every data schema.
192+-- The @t@ parameter imposes some restrictions on @type@ and @items@ properties (see @'SwaggerType'@ and @'SwaggerItems'@).
193+--
194+-- @'Schema'@ is used for request and response bodies and allows specifying objects
195+-- with properties in addition to what @'ParamSchema'@ provides.
196+--
197+-- In most cases you will have a Haskell data type for which you would like to
198+-- define a corresponding schema. To facilitate thise use case
199+-- this library provides two classes for schema encoding.
200+-- Both these classes provide means to encode /types/ as Swagger /schemas/.
187201--
188202-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,
189203-- such as query parameters, headers and URL path pieces.