chore: merge branch 'improve-spec' into dev

Author: mydearxym

lib/groupher_server/cms/delegates/article_curd.ex

@@ -130,6 +130,7 @@ defmodule GroupherServer.CMS.Delegate.ArticleCURD do
     end
   end
 
+  @spec ensure_author_exists(User.t()) :: {:ok, User.t()}
   def ensure_author_exists(%User{} = user) do
     # unique_constraint: avoid race conditions, make sure user_id unique
     # foreign_key_constraint: check foreign key: user_id exsit or not

lib/groupher_server/cms/delegates/community_sync.ex

@@ -6,9 +6,12 @@ defmodule GroupherServer.CMS.Delegate.CommunitySync do
   import Helper.ErrorCode
   # import ShortMaps
 
+  alias GroupherServer.CMS
+
   alias Helper.ORM
+  alias Helper.SpecType, as: T
 
-  alias GroupherServer.CMS.{
+  alias CMS.{
     Community,
     CommunityWiki,
     CommunityCheatsheet
@@ -17,6 +20,7 @@ defmodule GroupherServer.CMS.Delegate.CommunitySync do
   @doc """
   get wiki
   """
+  @spec get_wiki(Community.t()) :: {:ok, CommunityWiki.t()}
   def get_wiki(%Community{raw: raw}) do
     with {:ok, community} <- ORM.find_by(Community, raw: raw),
          {:ok, wiki} <- ORM.find_by(CommunityWiki, community_id: community.id) do
@@ -30,6 +34,7 @@ defmodule GroupherServer.CMS.Delegate.CommunitySync do
   @doc """
   get cheatsheet
   """
+  @spec get_cheatsheet(Community.t()) :: {:ok, CommunityCheatsheet.t()}
   def get_cheatsheet(%Community{raw: raw}) do
     with {:ok, community} <- ORM.find_by(Community, raw: raw),
          {:ok, wiki} <- ORM.find_by(CommunityCheatsheet, community_id: community.id) do
@@ -43,6 +48,7 @@ defmodule GroupherServer.CMS.Delegate.CommunitySync do
   @doc """
   sync wiki
   """
+  @spec sync_github_content(Community.t(), atom(), any()) :: {:ok, CommunityWiki.t()}
   def sync_github_content(%Community{id: id}, :wiki, attrs) do
     with {:ok, community} <- ORM.find(Community, id) do
       attrs = Map.merge(attrs, %{community_id: community.id})
@@ -54,6 +60,7 @@ defmodule GroupherServer.CMS.Delegate.CommunitySync do
   @doc """
   sync cheatsheet
   """
+  @spec sync_github_content(Community.t(), atom(), any()) :: {:ok, CommunityCheatsheet.t()}
   def sync_github_content(%Community{id: id}, :cheatsheet, attrs) do
     with {:ok, community} <- ORM.find(Community, id) do
       attrs = Map.merge(attrs, %{community_id: community.id})
@@ -65,10 +72,17 @@ defmodule GroupherServer.CMS.Delegate.CommunitySync do
   @doc """
   add contributor to exsit wiki contributors list
   """
+  @spec add_contributor(Community.t(), T.github_contributor()) ::
+          {:ok, CommunityWiki} | T.gq_error()
   def add_contributor(%CommunityWiki{id: id}, contributor_attrs) do
     do_add_contributor(CommunityWiki, id, contributor_attrs)
   end
 
+  @doc """
+  add contributor to exsit cheatsheet contributors list
+  """
+  @spec add_contributor(Community.t(), T.github_contributor()) ::
+          {:ok, CommunityCheatsheet} | T.gq_error()
   def add_contributor(%CommunityCheatsheet{id: id}, contributor_attrs) do
     do_add_contributor(CommunityCheatsheet, id, contributor_attrs)
   end

lib/helper/spec_type.ex

@@ -14,4 +14,17 @@ defmodule Helper.SpecType do
   @type done :: {:ok, map} | {:error, map}
 
   @type id :: non_neg_integer() | String.t()
+
+  @typedoc """
+  general contribute type for wiki and cheatshet
+  """
+  @type github_contributor2 :: %{
+          github_id: String.t(),
+          avatar: String.t(),
+          html_url: String.t(),
+          nickname: String.t(),
+          bio: nil | String.t(),
+          location: nil | String.t(),
+          company: nil | String.t()
+        }
 end