@@ -159,7 +159,7 @@ import Data.Swagger.Internal
159159-- $lens
160160--
161161-- Since @'Swagger'@ has a fairly complex structure, lenses and prisms are used
162−-- to work comfortly with it. In combination with @'Monoid'@ instances, lenses
162+-- to work comfortably with it. In combination with @'Monoid'@ instances, lenses
163163-- make it fairly simple to construct/modify any part of the specification:
164164--
165165-- >>> :{
@@ -173,13 +173,14 @@ import Data.Swagger.Internal
173173-- :}
174174-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"definitions\":{\"User\":{\"type\":\"string\"}},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"404\":{\"description\":\"User info not found\"},\"200\":{\"schema\":{\"$ref\":\"#/definitions/User\"},\"description\":\"OK\"}},\"produces\":[\"application/json\"]}}}}"
175175--
176−-- In the snippet above we declare API with a single path @/user@ providing method @GET@
177−-- which produces @application/json@ output and should respond with code @200@ and body specified
176+-- In the snippet above we declare an API with a single path @/user@. This path provides method @GET@
177+-- which produces @application/json@ output. It should respond with code @200@ and body specified
178178-- by schema @User@ which is defined in @'definitions'@ property of swagger specification.
179+-- Alternatively it may respond with code @404@ meaning that user info is not found.
179180--
180181-- For convenience, @swagger2@ uses /classy field lenses/. It means that
181182-- field accessor names can be overloaded for different types. One such
182−-- common field is @'description'@. Many components of Swagger specification
183+-- common field is @'description'@. Many components of a Swagger specification
183184-- can have descriptions, and you can use the same name for them:
184185--
185186-- >>> encode $ (mempty :: Response) & description .~ "No content"