Improve GraphQL documentation and cleanup API

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

lib/graphql/schema/todos/todo.ex

@@ -26,6 +26,9 @@ defmodule Mobilizon.GraphQL.Schema.Todos.TodoType do
     )
   end
 
+  @desc """
+  A paginated list of todos
+  """
   object :paginated_todo_list do
     field(:elements, list_of(:todo), description: "A list of todos")
     field(:total, :integer, description: "The total number of todos in the list")
@@ -34,7 +37,7 @@ defmodule Mobilizon.GraphQL.Schema.Todos.TodoType do
   object :todo_queries do
     @desc "Get a todo"
     field :todo, :todo do
-      arg(:id, non_null(:id))
+      arg(:id, non_null(:id), description: "The todo ID")
       resolve(&TodoResolver.get_todo/3)
     end
   end
@@ -42,23 +45,23 @@ defmodule Mobilizon.GraphQL.Schema.Todos.TodoType do
   object :todo_mutations do
     @desc "Create a todo"
     field :create_todo, :todo do
-      arg(:todo_list_id, non_null(:id))
-      arg(:title, non_null(:string))
-      arg(:status, :boolean)
-      arg(:due_date, :datetime)
-      arg(:assigned_to_id, :id)
+      arg(:todo_list_id, non_null(:id), description: "The todo-list ID this todo is in")
+      arg(:title, non_null(:string), description: "The todo title")
+      arg(:status, :boolean, description: "The todo status")
+      arg(:due_date, :datetime, description: "The todo due date")
+      arg(:assigned_to_id, :id, description: "The actor this todo is assigned to")
 
       resolve(&TodoResolver.create_todo/3)
     end
 
     @desc "Update a todo"
     field :update_todo, :todo do
-      arg(:id, non_null(:id))
-      arg(:todo_list_id, :id)
-      arg(:title, :string)
-      arg(:status, :boolean)
-      arg(:due_date, :datetime)
-      arg(:assigned_to_id, :id)
+      arg(:id, non_null(:id), description: "The todo ID")
+      arg(:todo_list_id, :id, description: "The new todo-list ID")
+      arg(:title, :string, description: "The new todo title")
+      arg(:status, :boolean, description: "The new todo status")
+      arg(:due_date, :datetime, description: "The new todo due date")
+      arg(:assigned_to_id, :id, description: "The new id of the actor this todo is assigned to")
 
       resolve(&TodoResolver.update_todo/3)
     end

lib/graphql/schema/todos/todo_list.ex

@@ -23,6 +23,9 @@ defmodule Mobilizon.GraphQL.Schema.Todos.TodoListType do
     )
   end
 
+  @desc """
+  A paginated list of todo-lists
+  """
   object :paginated_todo_list_list do
     field(:elements, list_of(:todo_list), description: "A list of todo lists")
     field(:total, :integer, description: "The total number of todo lists in the list")
@@ -31,7 +34,7 @@ defmodule Mobilizon.GraphQL.Schema.Todos.TodoListType do
   object :todo_list_queries do
     @desc "Get a todo list"
     field :todo_list, :todo_list do
-      arg(:id, non_null(:id))
+      arg(:id, non_null(:id), description: "The todo-list ID")
       resolve(&Todos.get_todo_list/3)
     end
   end
@@ -39,8 +42,8 @@ defmodule Mobilizon.GraphQL.Schema.Todos.TodoListType do
   object :todo_list_mutations do
     @desc "Create a todo list"
     field :create_todo_list, :todo_list do
-      arg(:title, non_null(:string))
-      arg(:group_id, non_null(:id))
+      arg(:title, non_null(:string), description: "The todo list title")
+      arg(:group_id, non_null(:id), description: "The group ID")
       resolve(&Todos.create_todo_list/3)
     end
   end