Add note about the use of args (#1170)

* Add note about the use of `args`

Closes #1037

* Some improvements

* Link to correct place

Author: jkimbo

docs/api/index.rst

@@ -20,6 +20,8 @@ Object types
 .. autoclass:: graphene.Mutation
     :members:
 
+.. _fields-mounted-types:
+
 Fields (Mounted Types)
 ----------------------
 

docs/types/objecttypes.rst

@@ -158,6 +158,22 @@ You can then execute the following query:
         }
     }
 
+*Note:* There are several arguments to a field that are "reserved" by Graphene
+(see :ref:`fields-mounted-types`).
+You can still define an argument that clashes with one of these fields by using
+the ``args`` parameter like so:
+
+.. code:: python
+
+    from graphene import ObjectType, Field, String
+
+    class Query(ObjectType):
+        answer = String(args={'description': String()})
+
+        def resolve_answer(parent, info, description):
+            return description
+
+
 Convenience Features of Graphene Resolvers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

graphene/types/field.py

@@ -40,11 +40,12 @@ class Person(ObjectType):
             last_name = graphene.Field(String, description='Surname')  # explicitly mounted as Field
 
     args:
-        type (class for a graphene.UnmountedType): must be a class (not an instance) of an
+        type (class for a graphene.UnmountedType): Must be a class (not an instance) of an
             unmounted graphene type (ex. scalar or object) which is used for the type of this
             field in the GraphQL schema.
-        args (optional, Dict[str, graphene.Argument]): arguments that can be input to the field.
-            Prefer to use **extra_args.
+        args (optional, Dict[str, graphene.Argument]): Arguments that can be input to the field.
+            Prefer to use ``**extra_args``, unless you use an argument name that clashes with one
+            of the Field arguments presented here (see :ref:`example<ResolverParamGraphQLArguments>`).
         resolver (optional, Callable): A function to get the value for a Field from the parent
             value object. If not set, the default resolver method for the schema is used.
         source (optional, str): attribute name to resolve for this field from the parent value