feat: add setup function with improved documentation

Add a proper setup function to initialize the plugin. The setup
function creates necessary autocommands and validates API key.

Type annotations were updated to improve developer experience:
- @Class and @field annotations for Article, Author, FeedArticle
- @param and @return annotations for all functions
- Changed vim.fn.json_decode to vim.json.decode

Author: Massolari

lua/devto-nvim/api.lua

@@ -2,18 +2,28 @@ local M = {}
 local notify = require("devto-nvim.notify")
 local article = require("devto-nvim.article")
 
+--- Get the API key from the environment
+--- @return string? The API key, or nil if it is not set
 function M.key()
   return vim.env.DEVTO_API_KEY
 end
 
+--- The base URL for the API
 local BASE_URL = "https://dev.to/api"
 
 ---@class Response
 ---@field status number
 ---@field body table
 
+---@class CurlOptions
+---@field headers table<string, string>?
+---@field body table?
+
 ---@alias Method "GET" | "POST" | "PUT" | "DELETE"
 
+--- Handle an error response
+--- If the response is successful, the `on_success` callback will be called with the response body
+--- If the response is an error, the error will be displayed to the user
 ---@param response Response
 ---@param on_success fun(body: table)
 function M.handle_error(response, on_success)
@@ -33,6 +43,7 @@ function M.handle_error(response, on_success)
   end
 end
 
+--- Convert a `vim.SystemCompleted` object to a `Response` object
 ---@param out vim.SystemCompleted
 ---@return Response
 local function system_completed_to_response(out)
@@ -51,7 +62,7 @@ local function system_completed_to_response(out)
   -- Only attempt to decode if we have a body
   if response_body and response_body ~= "" then
     -- Protect against JSON decode errors
-    body = vim.fn.json_decode(response_body)
+    body = vim.json.decode(response_body)
   end
 
   return {
@@ -60,14 +71,15 @@ local function system_completed_to_response(out)
   }
 end
 
----@param method Method
----@param endpoint string
----@param options table
----@param on_exit fun(response: Response)?
+--- Make a curl request
+---@param method Method The HTTP method to use
+---@param endpoint string The endpoint to hit
+---@param options CurlOptions Options to pass to curl
+---@param on_exit fun(response: Response)? A callback to run when the request is complete, if not provided the request will be synchronous
 ---@return vim.SystemObj
 local function curl(method, endpoint, options, on_exit)
   local headers = options.headers or {}
-  local request_body = options.body and { "-d", vim.fn.json_encode(options.body) } or {}
+  local request_body = options.body and { "-d", vim.json.encode(options.body) } or {}
 
   local cmd = vim.iter({
     "curl",
@@ -91,11 +103,13 @@ local function curl(method, endpoint, options, on_exit)
   end)
 end
 
----@param method Method
----@param endpoint string
----@param options table
+--- Make a synchronous request to the API
+---@param method Method The HTTP method to use
+---@param endpoint string The endpoint to hit
+---@param options CurlOptions Options to pass to curl
 ---@return Response
 local function request(method, endpoint, options)
+  ---@type CurlOptions
   local parameters = vim.tbl_extend(
     "force",
     {
@@ -114,10 +128,12 @@ local function request(method, endpoint, options)
   return response
 end
 
----@param method Method
----@param endpoint string
----@param on_success fun(body: table)
+--- Make an asynchronous request to the API
+---@param method Method The HTTP method to use
+---@param endpoint string The endpoint to hit
+---@param on_success fun(body: table) A callback to run when the request is successful
 local function request_async(method, endpoint, on_success)
+  ---@type CurlOptions
   local options = {
     headers = {
       "Api-Key: " .. M.key()
@@ -133,8 +149,9 @@ local function request_async(method, endpoint, on_success)
   )
 end
 
----@param endpoint string
----@param on_success fun(body: table)
+--- Make a asynchronous GET request to the API
+---@param endpoint string The endpoint to hit
+---@param on_success fun(body: table) A callback to run when the request is successful
 local function get(endpoint, on_success)
   request_async(
     "GET",
@@ -143,27 +160,33 @@ local function get(endpoint, on_success)
   )
 end
 
----@param endpoint string
----@param body table
+--- Make a synchronous PUT request to the API
+---@param endpoint string The endpoint to hit
+---@param body table The body of the request
 ---@return Response
 local function put(endpoint, body)
   return request("PUT", endpoint, { body = body })
 end
 
----@param endpoint string
----@param body table
+--- Make a synchronous POST request to the API
+---@param endpoint string The endpoint to hit
+---@param body table The body of the request
 ---@return Response
 local function post(endpoint, body)
   return request("POST", endpoint, { body = body })
 end
 
----@param on_success fun(body: table)
+--- Fetch all articles for the current user
+--- The request is asynchronous
+---@param on_success fun(body: table) A callback to run when the request is successful
 function M.my_articles(on_success)
   return get("/articles/me/all", on_success)
 end
 
----@param id number
----@param content string
+--- Save an article
+--- The request is synchronous
+---@param id number The ID of the article to save
+---@param content string The new content of the article
 ---@return Response
 function M.save_article(id, content)
   return put(
@@ -172,7 +195,9 @@ function M.save_article(id, content)
   )
 end
 
----@param title string
+--- Create a new article
+--- The request is synchronous
+---@param title string The title of the new article
 ---@return Response
 function M.new_article(title)
   return post(
@@ -181,22 +206,28 @@ function M.new_article(title)
   )
 end
 
----@param on_success fun(body: table)
+--- Fetch the feed of articles of the current user
+--- The request is asynchronous
+---@param on_success fun(body: FeedArticle[]) A callback to run when the request is successful
 function M.feed(on_success)
   get("/articles", on_success)
 end
 
----@param id number
----@param on_success fun(body: table)
+--- Fetch an article by ID
+--- The request is asynchronous
+---@param id number The ID of the article to fetch
+---@param on_success fun(body: table) A callback to run when the request is successful
 function M.get_article(id, on_success)
   get(
     "/articles/" .. tostring(id),
     on_success
   )
 end
 
----@param path string
----@param on_success fun(body: table)
+--- Fetch an article by path
+--- The request is asynchronous
+---@param path string The path of the article to fetch
+---@param on_success fun(body: table) A callback to run when the request is successful
 function M.get_article_by_path(path, on_success)
   get("/articles/" .. path, on_success)
 end

lua/devto-nvim/article.lua

@@ -1,15 +1,39 @@
---[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
 local M = {}
 
--- TODO: Create class for Article
+---@class Article
+---@field id number
+---@field type_of string
+---@field title string
+---@field slug string
+---@field description string
+---@field url string
+---@field body_markdown string?
+---@field user Author
+---@field reading_time_minutes number
+---@field tags string[]
+---@field positive_reactions_count number
+---@field comments_count number
+---@field readable_publish_date string
+---@field published_at string?
 
+---@class Author
+---@field name string
+---@field username string
+
+--- Get the lines of the body of an article
+--- @param article Article
+--- @return string[]
 function M.get_body_lines(article)
   return vim.split(article.body_markdown or "", "\n")
 end
 
+--- Get the template for a new article
+--- @param title string The title of the new article
+--- @return string
 function M.get_template(title)
-  return ("---\ntitle: " .. title) ..
-      "\npublished: false\ndescription:\ntags:\n# cover_image: https://direct_url_to_image.jpg\n# Use a ratio of 100:42 for best results.\n---\n\n"
+  return string.format(
+    "---\ntitle: %s\npublished: false\ndescription:\ntags:\n# cover_image: https://direct_url_to_image.jpg\n# Use a ratio of 100:42 for best results.\n---\n\n",
+    title)
 end
 
 return M

lua/devto-nvim/buffer.lua

@@ -3,14 +3,18 @@ local Article = require("devto-nvim.article")
 local util = require("devto-nvim.util")
 local set_locals = util.set_locals
 
-M.set_basic_options = function()
+--- Set the basic options for a markdown buffer
+function M.set_basic_options()
   set_locals({
     filetype = "markdown",
     modified = false
   })
 end
 
-M.write = function(buffer, lines, offset)
+--- Write lines to a buffer
+--- @param buffer number The buffer to write to
+--- @param lines string[] The lines to write
+function M.write(buffer, lines, offset)
   local modifiable = vim.opt_local.modifiable:get()
   vim.opt_local.modifiable = true
   vim.api.nvim_buf_set_lines(
@@ -23,7 +27,9 @@ M.write = function(buffer, lines, offset)
   vim.opt_local.modifiable = modifiable
 end
 
-M.get_content = function()
+--- Get the content of the current buffer
+--- @return {content: string, bufnr: number}
+function M.get_content()
   local buffer = vim.api.nvim_get_current_buf()
   local lines = vim.api.nvim_buf_get_lines(buffer, 0, -1, true)
   return {
@@ -32,7 +38,9 @@ M.get_content = function()
   }
 end
 
-M.open_my_article = function(article)
+--- Open an article of the current user in a buffer by its ID
+--- @param article Article The article to open
+function M.open_my_article(article)
   vim.cmd(":edit devto://my-article/" .. tostring(article.id))
   local buffer = vim.api.nvim_get_current_buf()
   M.write(
@@ -43,7 +51,9 @@ M.open_my_article = function(article)
   set_locals({ buftype = "acwrite", swapfile = false })
 end
 
-M.load_article = function(article)
+--- Open an article in a buffer by its title
+--- @param article Article The article to open
+function M.load_article(article)
   vim.cmd(":edit devto://article/" .. article.title)
   set_locals({ linebreak = true, textwidth = 80 })
   local buffer = vim.api.nvim_get_current_buf()