Improvements to the inline doc

src/main/scala/com/gu/contentapi/porter/graphql/ContentQueryParameters.scala

@@ -11,7 +11,7 @@ object ContentQueryParameters {
   val ContentIdArg = Argument("id", OptionInputType(StringType), description = "get one article by ID")
   val QueryString = Argument("q", OptionInputType(StringType), description = "an Elastic Search query string to search for content")
   val QueryFields = Argument("queryFields", OptionInputType(ListInputType(StringType)), description = "fields to perform a query against. Defaults to webTitle and path.")
-  val TagArg = Argument("tags", OptionInputType(ListInputType(StringType)), description = "look up articles associated with all of these tag IDs")
+  val TagArg = Argument("tags", OptionInputType(ListInputType(StringType)), description = "look up articles associated with all of these tag IDs. If you don't have exact tag IDs you should instead make a root query on Tags and use the `matchingContent` or `matchingAnyTag` selectors")
   val ExcludeTagArg = Argument("excludeTags", OptionInputType(ListInputType(StringType)), description = "don't include any articles with these tag IDs")
   val SectionArg = Argument("sectionId", OptionInputType(ListInputType(StringType)), description = "look up articles in any of these sections")
   val ExcludeSectionArg = Argument("excludeSections", OptionInputType(ListInputType(StringType)), description = "don't include any articles with these tag IDs")

src/main/scala/com/gu/contentapi/porter/graphql/RootQuery.scala

@@ -86,6 +86,8 @@ object RootQuery {
   val Query = ObjectType[GQLQueryContext, Unit](
     "Query", fields[GQLQueryContext, Unit](
       Field("article", ArticleEdge,
+        description = Some("An Article is the main unit of our publication.  You can search articles directly here, or query" +
+          " tags or sections to see what articles live within it."),
         arguments = ContentQueryParameters.AllContentQueryParameters,
         resolve = ctx =>
           ctx arg ContentQueryParameters.ContentIdArg match {
@@ -101,6 +103,8 @@ object RootQuery {
           }
       ),
       Field("tag", TagEdge,
+        description = Some("The Guardian uses tags to group similar pieces of content together across multiple different viewpoints.  " +
+          "Tags are a closed set, which can be searched here, and there are different types of tags which represent different viewpoints"),
         arguments = TagQueryParameters.AllTagQueryParameters,
         resolve = ctx =>
           ctx.ctx.repo.marshalledTags(ctx arg TagQueryParameters.QueryString,
@@ -114,6 +118,8 @@ object RootQuery {
             ctx arg PaginationParameters.Limit, ctx arg PaginationParameters.Cursor)
       ),
       Field("atom", AtomEdge,
+        description = Some("An Atom is a piece of content which can be linked to multiple articles but may have a production lifecycle independent" +
+          " of these articles.  Examples are cartoons, videos, quizzes, call-to-action blocks, etc."),
         arguments = AtomQueryParameters.AllParameters,
         resolve = ctx=>
       ctx.ctx.repo.atoms(ctx arg AtomQueryParameters.AtomIds, ctx arg AtomQueryParameters.QueryString, ctx arg AtomQueryParameters.QueryFields,