Improve GraphQL documentation and cleanup API

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

lib/graphql/schema/events/feed_token.ex

@@ -10,7 +10,12 @@ defmodule Mobilizon.GraphQL.Schema.Events.FeedTokenType do
   alias Mobilizon.{Actors, Users}
   alias Mobilizon.GraphQL.Resolvers.FeedToken
 
-  @desc "Represents a participant to an event"
+  @desc """
+  Represents a feed token
+
+  Feed tokens are tokens that are used to provide access to private feeds such as WebCal feed for all of your user's events,
+  or an Atom feed for just a profile.
+  """
   object :feed_token do
     field(
       :actor,
@@ -31,21 +36,21 @@ defmodule Mobilizon.GraphQL.Schema.Events.FeedTokenType do
 
   @desc "Represents a deleted feed_token"
   object :deleted_feed_token do
-    field(:user, :deleted_object)
-    field(:actor, :deleted_object)
+    field(:user, :deleted_object, description: "The user that owned the deleted feed token")
+    field(:actor, :deleted_object, description: "The actor that owned the deleted feed token")
   end
 
   object :feed_token_mutations do
     @desc "Create a Feed Token"
     field :create_feed_token, :feed_token do
-      arg(:actor_id, :id)
+      arg(:actor_id, :id, description: "The actor ID for the feed token")
 
       resolve(&FeedToken.create_feed_token/3)
     end
 
     @desc "Delete a feed token"
     field :delete_feed_token, :deleted_feed_token do
-      arg(:token, non_null(:string))
+      arg(:token, non_null(:string), description: "The token to delete")
 
       resolve(&FeedToken.delete_feed_token/3)
     end

lib/graphql/schema/events/participant.ex

@@ -37,6 +37,9 @@ defmodule Mobilizon.GraphQL.Schema.Events.ParticipantType do
     field(:inserted_at, :datetime, description: "The datetime this participant was created")
   end
 
+  @desc """
+  Metadata about a participant
+  """
   object :participant_metadata do
     field(:cancellation_token, :string,
       description: "The eventual token to leave an event when user is anonymous"
@@ -46,61 +49,66 @@ defmodule Mobilizon.GraphQL.Schema.Events.ParticipantType do
     field(:locale, :string, description: "The participant's locale")
   end
 
+  @desc """
+  A paginated list of participants
+  """
   object :paginated_participant_list do
     field(:elements, list_of(:participant), description: "A list of participants")
     field(:total, :integer, description: "The total number of participants in the list")
   end
 
+  @desc """
+  The possible values for a participant role
+  """
   enum :participant_role_enum do
-    value(:not_approved)
-    value(:not_confirmed)
-    value(:participant)
-    value(:moderator)
-    value(:administrator)
-    value(:creator)
-    value(:rejected)
+    value(:not_approved, description: "The participant has not been approved")
+    value(:not_confirmed, description: "The participant has not confirmed their participation")
+    value(:participant, description: "The participant is a regular participant")
+    value(:moderator, description: "The participant is an event moderator")
+    value(:administrator, description: "The participant is an event administrator")
+    value(:creator, description: "The participant is an event creator")
+    value(:rejected, description: "The participant has been rejected from this event")
   end
 
   @desc "Represents a deleted participant"
   object :deleted_participant do
-    field(:id, :id)
-    field(:event, :deleted_object)
-    field(:actor, :deleted_object)
+    field(:id, :id, description: "The participant ID")
+    field(:event, :deleted_object, description: "The participant's event")
+    field(:actor, :deleted_object, description: "The participant's actor")
   end
 
   object :participant_mutations do
     @desc "Join an event"
     field :join_event, :participant do
-      arg(:event_id, non_null(:id))
-      arg(:actor_id, non_null(:id))
-      arg(:email, :string)
-      arg(:message, :string)
-      arg(:locale, :string)
+      arg(:event_id, non_null(:id), description: "The event ID that is joined")
+      arg(:actor_id, non_null(:id), description: "The actor ID for the participant")
+      arg(:email, :string, description: "The anonymous participant's email")
+      arg(:message, :string, description: "The anonymous participant's message")
+      arg(:locale, :string, description: "The anonymous participant's locale")
 
       resolve(&Participant.actor_join_event/3)
     end
 
     @desc "Leave an event"
     field :leave_event, :deleted_participant do
-      arg(:event_id, non_null(:id))
-      arg(:actor_id, non_null(:id))
-      arg(:token, :string)
+      arg(:event_id, non_null(:id), description: "The event ID the participant left")
+      arg(:actor_id, non_null(:id), description: "The actor ID for the participant")
+      arg(:token, :string, description: "The anonymous participant participation token")
 
       resolve(&Participant.actor_leave_event/3)
     end
 
-    @desc "Accept a participation"
+    @desc "Update a participation"
     field :update_participation, :participant do
-      arg(:id, non_null(:id))
-      arg(:role, non_null(:participant_role_enum))
-      arg(:moderator_actor_id, non_null(:id))
+      arg(:id, non_null(:id), description: "The participant ID")
+      arg(:role, non_null(:participant_role_enum), description: "The participant new role")
 
       resolve(&Participant.update_participation/3)
     end
 
     @desc "Confirm a participation"
     field :confirm_participation, :participant do
-      arg(:confirmation_token, non_null(:string))
+      arg(:confirmation_token, non_null(:string), description: "The participation token")
       resolve(&Participant.confirm_participation_from_token/3)
     end
   end