From 87057101b0e14eb51ff9367dfe9c5522ea933161 Mon Sep 17 00:00:00 2001 From: Ekaterina Vaartis Date: Tue, 10 Sep 2019 21:34:57 +0300 Subject: [PATCH] Add documentation for the emoji api endpoints --- .../web/emoji_api/emoji_api_controller.ex | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/lib/pleroma/web/emoji_api/emoji_api_controller.ex b/lib/pleroma/web/emoji_api/emoji_api_controller.ex index dffb91b0f..dc676b00f 100644 --- a/lib/pleroma/web/emoji_api/emoji_api_controller.ex +++ b/lib/pleroma/web/emoji_api/emoji_api_controller.ex @@ -16,6 +16,12 @@ def reload(conn, _params) do @cache_seconds_per_file Pleroma.Config.get!([:emoji, :shared_pack_cache_seconds_per_file]) + @doc """ + Lists the packs available on the instance as JSON. + + The information is public and does not require authentification. The format is + a map of "pack directory name" to pack.json contents. + """ def list_packs(conn, _params) do pack_infos = case File.ls(@emoji_dir_path) do @@ -116,6 +122,10 @@ defp make_archive(name, pack, pack_dir) do zip_result end + @doc """ + An endpoint for other instances (via admin UI) or users (via browser) + to download packs that the instance shares. + """ def download_shared(conn, %{"name" => name}) do pack_dir = Path.join(@emoji_dir_path, name) pack_file = Path.join(pack_dir, "pack.json") @@ -143,6 +153,13 @@ def download_shared(conn, %{"name" => name}) do end end + @doc """ + An admin endpoint to request downloading a pack named `pack_name` from the instance + `instance_address`. + + If the requested instance's admin chose to share the pack, it will be downloaded + from that instance, otherwise it will be downloaded from the fallback source, if there is one. + """ def download_from(conn, %{"instance_address" => address, "pack_name" => name} = data) do list_uri = "#{address}/api/pleroma/emoji/packs/list" @@ -211,6 +228,9 @@ def download_from(conn, %{"instance_address" => address, "pack_name" => name} = end end + @doc """ + Creates an empty pack named `name` which then can be updated via the admin UI. + """ def create(conn, %{"name" => name}) do pack_dir = Path.join(@emoji_dir_path, name) @@ -232,6 +252,9 @@ def create(conn, %{"name" => name}) do end end + @doc """ + Deletes the pack `name` and all it's files. + """ def delete(conn, %{"name" => name}) do pack_dir = Path.join(@emoji_dir_path, name) @@ -244,6 +267,11 @@ def delete(conn, %{"name" => name}) do end end + @doc """ + An endpoint to update `pack_names`'s metadata. + + `new_data` is the new metadata for the pack, that will replace the old metadata. + """ def update_metadata(conn, %{"pack_name" => name, "new_data" => new_data}) do pack_dir = Path.join(@emoji_dir_path, name) pack_file_p = Path.join(pack_dir, "pack.json") @@ -296,6 +324,20 @@ def update_metadata(conn, %{"pack_name" => name, "new_data" => new_data}) do end end + @doc """ + Updates a file in a pack. + + Updating can mean three things: + + - `add` adds an emoji named `shortcode` to the pack `pack_name`, + that means that the emoji file needs to be uploaded with the request + (thus requiring it to be a multipart request) and be named `file`. + There can also be an optional `filename` that will be the new emoji file name + (if it's not there, the name will be taken from the uploaded file). + - `update` changes emoji shortcode (from `shortcode` to `new_shortcode` or moves the file + (from the current filename to `new_filename`) + - `remove` removes the emoji named `shortcode` and it's associated file + """ def update_file( conn, %{"pack_name" => pack_name, "action" => action, "shortcode" => shortcode} = params @@ -447,6 +489,16 @@ def update_file( end end + @doc """ + Imports emoji from the filesystem. + + Importing means checking all the directories in the + `$instance_static/emoji/` for directories which do not have + `pack.json`. If one has an emoji.txt file, that file will be used + to create a `pack.json` file with it's contents. If the directory has + neither, all the files with specific configured extenstions will be + assumed to be emojis and stored in the new `pack.json` file. + """ def import_from_fs(conn, _params) do case File.ls(@emoji_dir_path) do {:error, _} ->