Improve GraphQL documentation and cleanup API

Signed-off-by: Thomas Citharel <tcit@tcit.fr>

lib/graphql/schema/actors/person.ex

@@ -58,8 +58,8 @@ defmodule Mobilizon.GraphQL.Schema.Actors.PersonType do
     field(:organized_events, :paginated_event_list,
       description: "A list of the events this actor has organized"
     ) do
-      arg(:page, :integer, default_value: 1)
-      arg(:limit, :integer, default_value: 10)
+      arg(:page, :integer, default_value: 1, description: "The page in the paginated event list")
+      arg(:limit, :integer, default_value: 10, description: "The limit of events per page")
       resolve(&Person.organized_events_for_person/3)
     end
 
@@ -68,8 +68,14 @@ defmodule Mobilizon.GraphQL.Schema.Actors.PersonType do
       description: "The list of events this person goes to"
     ) do
       arg(:event_id, :id)
-      arg(:page, :integer, default_value: 1)
-      arg(:limit, :integer, default_value: 10)
+
+      arg(:page, :integer,
+        default_value: 1,
+        description: "The page in the paginated participation list"
+      )
+
+      arg(:limit, :integer, default_value: 10, description: "The limit of participations per page")
+
       resolve(&Person.person_participations/3)
     end
 
@@ -81,6 +87,14 @@ defmodule Mobilizon.GraphQL.Schema.Actors.PersonType do
     end
   end
 
+  @desc """
+  A paginated list of persons
+  """
+  object :paginated_person_list do
+    field(:elements, list_of(:person), description: "A list of persons")
+    field(:total, :integer, description: "The total number of persons in the list")
+  end
+
   object :person_queries do
     @desc "Get the current actor for the logged-in user"
     field :logged_person, :person do
@@ -89,13 +103,13 @@ defmodule Mobilizon.GraphQL.Schema.Actors.PersonType do
 
     @desc "Get a person by its (federated) username"
     field :fetch_person, :person do
-      arg(:preferred_username, non_null(:string))
+      arg(:preferred_username, non_null(:string), description: "The person's federated username")
       resolve(&Person.fetch_person/3)
     end
 
     @desc "Get a person by its ID"
     field :person, :person do
-      arg(:id, non_null(:id))
+      arg(:id, non_null(:id), description: "The person ID")
       resolve(&Person.get_person/3)
     end
 
@@ -104,14 +118,20 @@ defmodule Mobilizon.GraphQL.Schema.Actors.PersonType do
       resolve(&Person.identities/3)
     end
 
-    field :persons, :persons do
-      arg(:preferred_username, :string, default_value: "")
-      arg(:name, :string, default_value: "")
-      arg(:domain, :string, default_value: "")
-      arg(:local, :boolean, default_value: true)
-      arg(:suspended, :boolean, default_value: false)
-      arg(:page, :integer, default_value: 1)
-      arg(:limit, :integer, default_value: 10)
+    @desc "List the profiles"
+    field :persons, :paginated_person_list do
+      arg(:preferred_username, :string, default_value: "", description: "Filter by username")
+      arg(:name, :string, default_value: "", description: "Filter by name")
+      arg(:domain, :string, default_value: "", description: "Filter by domain")
+
+      arg(:local, :boolean,
+        default_value: true,
+        description: "Filter by profile being local or not"
+      )
+
+      arg(:suspended, :boolean, default_value: false, description: "Filter by suspended status")
+      arg(:page, :integer, default_value: 1, description: "The page in the paginated person list")
+      arg(:limit, :integer, default_value: 10, description: "The limit of persons per page")
       resolve(&Person.list_persons/3)
     end
   end
@@ -119,7 +139,7 @@ defmodule Mobilizon.GraphQL.Schema.Actors.PersonType do
   object :person_mutations do
     @desc "Create a new person for user"
     field :create_person, :person do
-      arg(:preferred_username, non_null(:string))
+      arg(:preferred_username, non_null(:string), description: "The username for the profile")
 
       arg(:name, :string, description: "The displayed name for the new profile", default_value: "")
 
@@ -140,7 +160,7 @@ defmodule Mobilizon.GraphQL.Schema.Actors.PersonType do
 
     @desc "Update an identity"
     field :update_person, :person do
-      arg(:id, non_null(:id))
+      arg(:id, non_null(:id), description: "The person's ID")
 
       arg(:name, :string, description: "The displayed name for this profile")
 
@@ -161,14 +181,14 @@ defmodule Mobilizon.GraphQL.Schema.Actors.PersonType do
 
     @desc "Delete an identity"
     field :delete_person, :person do
-      arg(:id, non_null(:id))
+      arg(:id, non_null(:id), description: "The person's ID")
 
       resolve(&Person.delete_person/3)
     end
 
     @desc "Register a first profile on registration"
     field :register_person, :person do
-      arg(:preferred_username, non_null(:string))
+      arg(:preferred_username, non_null(:string), description: "The username for the profile")
 
       arg(:name, :string, description: "The displayed name for the new profile", default_value: "")
 
@@ -190,16 +210,18 @@ defmodule Mobilizon.GraphQL.Schema.Actors.PersonType do
   end
 
   object :person_subscriptions do
+    @desc "Notify when a person's participation's status changed for an event"
     field :event_person_participation_changed, :person do
-      arg(:person_id, non_null(:id))
+      arg(:person_id, non_null(:id), description: "The person's ID")
 
       config(fn args, _ ->
         {:ok, topic: args.person_id}
       end)
     end
 
+    @desc "Notify when a person's membership's status changed for a group"
     field :group_membership_changed, :person do
-      arg(:person_id, non_null(:id))
+      arg(:person_id, non_null(:id), description: "The person's ID")
 
       config(fn args, _ ->
         {:ok, topic: args.person_id}