Generate docs

3 files changed, 121 insertions, 140 deletions

diff --git a/lua/null-browser/api.lua b/lua/null-browser/api.lua
index e1f2acc..6d6f974 100644
--- a/lua/null-browser/api.lua
+++ b/lua/null-browser/api.lua
@@ -1,8 +1,10 @@
---- Internal api (unstable)
---- @type table
-__internals = __internals
+---@diagnostic disable: doc-field-no-class, undefined-doc-param
+--- Lua api for configuring null browser.
+--- @module web
+
 
---- @type table
+--- Internal api (unstable)
+_G.__internals = _G.__internals
 _G.web = _G.web or {}
 web.search = web.search or {}
 web.keymap = web.keymap or {}
@@ -13,7 +15,9 @@ web.decorations = web.decorations or {}
 
 require 'null-browser.utils'
 
---- @param fn fun(): nil  Schedule a function to be called on next tick (qt+libuv event loop)
+--- Schedule a function to be called on next tick (qt+libuv event loop)
+---
+--- @param fn fun():nil   Function to call
 function web.schedule(fn) __internals.schedule(fn) end
 
 --- Add a keymap
@@ -22,111 +26,89 @@ function web.schedule(fn) __internals.schedule(fn) end
 --- @param key    string           Key sequence (Eg: `<c-t>j`)
 --- @param action function         Function to run when keymap is triggered
 ---
---- @example
---- ```lua
+--- @usage
 --- web.keymap.set('n', 'o', function()
 ---   web.view.create('https://google.com')
 --- end)
---- ```
 function web.keymap.set(mode, key, action) return __internals.keymap_set(mode, key, action) end
 
 --- Set the current keymap mode
 ---
 --- @param mode string    The keymap mode to set
 ---
---- @example
---- ```lua
+--- @usage
 --- web.keymap.set_mode('n') -- Set to normal mode
 --- web.keymap.set_mode('i') -- Set to insert mode
---- ```
 function web.keymap.set_mode(mode) return __internals.keymap_set_mode(mode) end
 
 --- Get the current keymap mode
 ---
---- @example
---- ```lua
+--- @usage
 --- local current_mode = web.keymap.get_mode()
---- ```
 function web.keymap.get_mode() return __internals.keymap_get_mode() end
 
 --- Close view
 ---
 --- @param view_id?  number    View id to close
 ---
---- @example
---- ```lua
+--- @usage
 --- web.view.close()  -- Close current view in active window
 --- web.view.close(3) -- Close view with id 3
---- ```
 function web.view.close(view_id) return __internals.view_close(view_id) end
 
 --- Create a new view with a url
 ---
 --- @param url      string    Url to open in the new view
 ---
---- @example
---- ```lua
+--- @usage
 --- web.view.create('https://duckduckgo.com') -- Opens url in new view
 --- web.view.create() -- Opens new_view_url by default
---- ```
 function web.view.create(url) return __internals.view_create(url) end
 
 --- Get current view id
 ---
 --- @return number view_id Current view id
 ---
---- @example
---- ```lua
+--- @usage
 --- local view_id = web.view.current()
---- ```
 function web.view.current() return __internals.view_current() end
 
 --- Get a list of views in the current window
 ---
 --- @return table views  List of views
 ---
---- @example
---- ```lua
+--- @usage
 --- local views = web.view.list()
 --- print(views[1].url, views[1].title, views[1].id)
---- ```
 function web.view.list() return __internals.view_list() end
 
 --- Select a view in current window
 ---
 --- @param view_id number View id to select
 ---
---- @example
---- ```lua
+--- @usage
 --- web.view.select(3) -- Select view with id 3
---- ```
 function web.view.select(view_id) return __internals.view_select(view_id) end
 
 --- Set url of a given view
 ---
 --- @param url string      Url to open
---- @param view_id? number  View id to select
+--- @param view_id number?  View id to select
 ---
---- @example
---- ```lua
+--- @usage
 --- web.view.set_url('https://foobar.com')
 --- web.view.set_url('https://foobar.com', 3) -- Set url for view with id 3
---- ```
 function web.view.set_url(url, view_id) return __internals.view_set_url(url, view_id) end
 
---- @class SetHTMLOpts
---- @field view? number View id
-
---- Set html in a given view
+--- Set html inside the page for a given view
 ---
---- @param html string        HTML string
---- @param opts? SetHTMLOpts  Options
+--- @param html      string   HTML string
+--- @param opts      table    Options
+--- @param opts.view number   View id
 ---
---- @example
---- ```lua
+--- @usage
 --- web.view.set_html('<h2>HJello</h2>')
 --- web.view.set_html('<h2>HJello</h2>', { view = 3 }) -- Set html for view with id 3
---- ```
 function web.view.set_html(html, opts) return __internals.view_set_html(html, (opts or {}).view) end
 
 --- @class RunJSOpts
@@ -138,11 +120,9 @@ function web.view.set_html(html, opts) return __internals.view_set_html(html, (o
 --- @param js string        HTML string
 --- @param opts? RunJSOpts  Options
 ---
---- @example
---- ```lua
+--- @usage
 --- web.view.run_js('console.log(42)')
 --- web.view.run_js('console.log(42)', { view = 3 }) -- Set html for view with id 3
---- ```
 function web.view.run_js(js, opts) return __internals.view_run_js(js, opts or {}) end
 
 --- @class ReloadOpts
@@ -150,13 +130,11 @@ function web.view.run_js(js, opts) return __internals.view_run_js(js, opts or {}
 
 --- Relaod a given view
 ---
---- @param opts? RunJSOpts  Options
+--- @param opts? ReloadOpts  Options
 ---
---- @example
---- ```lua
+--- @usage
 --- web.view.reload()
 --- web.view.reload({ view = 3 }) -- Reload view with id 3
---- ```
 function web.view.reload(opts) return __internals.view_reload((opts or {}).view) end
 
 --- @class ExposeOpts
@@ -164,41 +142,35 @@ function web.view.reload(opts) return __internals.view_reload((opts or {}).view)
 
 --- Expose a lua function inside a view (Only works with decorations)
 ---
---- @param name string             Func name
---- @param action fun(table):nil   Action to call when function is invoked in view
---- @param opts? ExposeOpts        Options
+--- @param name    string             Func name
+--- @param action  fun(table):nil     Action to call when function is invoked in view
+--- @param opts    ExposeOpts?        Options
 ---
---- @example
---- ```lua
---- web.view.expose('tab_select', function(args)
+--- @usage
+--- web.view.expose('tabSelect', function(args)
 ---   web.view.select(tonumber(args.view))
 --- end)
---- ```
---- then in js
---- ```js
---- _nullbrowser.rpc.tab_select({ view: 5 })
---- ```
+---
+--- @usage
+--- -- In javascript
+--- _nullbrowser.rpc.tabSelect({ view: 5 })
 function web.view.expose(name, action, opts) return __internals.view_expose(name, action, (opts or {}).view) end
 
 --- Open devtools window for the view
 ---
---- @param view_id? number    Id of the view
+--- @param view_id number?    Id of the view
 ---
---- @example
---- ```lua
+--- @usage
 --- web.view.open_devtools() -- Open devtools window for current view
 --- web.view.open_devtools(5) -- Open devtools window for view id 5
---- ```
 function web.view.open_devtools(view_id) return __internals.view_open_devtools(view_id) end
 
 --- Get current view index
 ---
 --- @return number|nil index Current view index
 ---
---- @example
---- ```lua
+--- @usage
 --- local index = web.view.current_index()
---- ```
 function web.view.current_index()
   local current_view = web.view.current();
   for index, view in ipairs(web.view.list()) do
@@ -210,21 +182,16 @@ function web.view.current_index()
 end
 
 --- Listen to events from the browser
+--- @param events string|table              Event or events to listen to
+--- @param opts table                       Options
+--- @param opts.callback fun(opts:any):nil  Callback called when that event occurs
 ---
---- @class nullb.EventListenerOptions
---- @field callback any  Callback called when that event occurs
----
---- @param events string|table             Event or events to listen to
---- @param opts nullb.EventListenerOptions  Options
----
---- @example
---- ```lua
+--- @usage
 --- web.event.add_listener('UrlChanged', {
 ---   callback = function(opts)
 ---     print(opts.url, opts.tab, opts.win)
 ---   end,
 --- })
---- ```
 function web.event.add_listener(events, opts)
   opts = web.utils.table_merge({}, opts or {})
   if type(events) == "string" then events = { events } end
@@ -234,17 +201,41 @@ function web.event.add_listener(events, opts)
 end
 
 --- Set configuration options
+--- @see WebOpts
 ---
 --- @param key string                        The name of the configuration
 --- @param value nil|string|boolean|number   Configuration value
 ---
---- @example
---- ```lua
+--- @usage
 --- web.set('new_view_url', 'https://duckduckgo.com')
---- ```
+--- -- Can also be written as
+--- web.opts.new_view_url = 'https://duckduckgo.com'
 function web.set(key, value) __internals.config_set(key, value) end
 
---- Web options. Calls web.set/web.get for options
+--- Get configuration value
+--- @see WebOpts
+---
+--- @param key string The name of the configuration
+---
+--- @usage
+--- local url = web.get('new_view_url')
+function web.get(key) return __internals.config_get(key) end
+
+--- Maps to values defined in ./src/Configuration.hpp
+--- @table WebOpts
+--- @field app_data_dir string                 (readonly) Directory where app data is stored
+--- @field close_window_when_no_views boolean  If true, when the last tab in a window is closed, the window closes (default: true)
+--- @field config_dir string                   (readonly) Directory where app config is stored
+--- @field downloads_dir string                Directory where downloaded files go
+--- @field new_view_url string                 URL used when view url is not specified (default: 'https://duckduckgo.com')
+--- @field permissions_persistance 'always'|'session'|'never'  How to persist choices for permissions (default: 'always')
+--- @field user_agent string                   User agent sent by the browser
+
+--- API for configuring browser options
+--- @see WebOpts
+---
+--- @usage
+--- web.opts.new_view_url = 'https://duckduckgo.com'
 web.opts = setmetatable({}, {
   __index = function(_, key)
     return web.get(key)
@@ -254,89 +245,65 @@ web.opts = setmetatable({}, {
   end,
 })
 
---- Get configuration value
----
---- @param key string The name of the configuration
----
---- @example
---- ```lua
---- local url = web.get('new_view_url')
---- ```
-function web.get(key) return __internals.config_get(key) end
-
 --- Go back in history for given view
 ---
---- @param count?   number     Number of history items to go back in (default = 1)
---- @param view_id? number   Id of the view
+--- @param count   number?     Number of history items to go back in (default = 1)
+--- @param view_id number?   Id of the view
 ---
---- @example
---- ```lua
+--- @usage
 --- web.history.back(2, 3) -- Go back 2 history items for view id 3
---- ```
 function web.history.back(count, view_id) return __internals.history_back(count, view_id) end
 
 --- Go forward in history for given view
 ---
---- @param count?   number     Number of history items to go forward in (default = 1)
---- @param view_id? number   Id of the view
+--- @param count   number?     Number of history items to go forward in (default = 1)
+--- @param view_id number?   Id of the view
 ---
---- @example
---- ```lua
+--- @usage
 --- web.history.forward(2, 3) -- Go forward 2 history items for view id 3
---- ```
 function web.history.forward(count, view_id) return __internals.history_forward(count, view_id) end
 
 --- Search text inside a view
 ---
---- @param text    string     Text to search
---- @param view_id? number    Id of the view
+--- @param text    string?     Text to search
+--- @param view_id number?    Id of the view
 ---
---- @example
---- ```lua
+--- @usage
 --- web.search.set_text('whatever') -- Search in current view
 --- web.search.set_text('whatever', 5) -- Search in view id 5
---- ```
 function web.search.set_text(text, view_id) return __internals.search_set_text(text, view_id) end
 
 --- Reset searched text in a view (Same as web.search.set_text(''))
 ---
---- @param view_id? number    Id of the view
+--- @param view_id number?    Id of the view
 ---
---- @example
---- ```lua
+--- @usage
 --- web.search.reset() -- Reset search state for current view
 --- web.search.reset(5) -- Reset search state for view id 5
---- ```
 function web.search.reset(view_id) return __internals.search_set_text('', view_id) end
 
 --- Get the last searched text
 ---
---- @example
---- ```lua
+--- @usage
 --- local text = web.search.get_text()
---- ```
 function web.search.get_text() return __internals.search_get_text() end
 
 --- Highlight next search term for the last searched text
 ---
---- @param view_id? number    Id of the view
+--- @param view_id number?    Id of the view
 ---
---- @example
---- ```lua
+--- @usage
 --- web.search.next() -- Next search result in current view
 --- web.search.next(5) -- Next search result in view id 5
---- ```
 function web.search.next(view_id) return __internals.search_next(view_id) end
 
 --- Highlight previous search term for the last searched text
 ---
---- @param view_id? number    Id of the view
+--- @param view_id number?    Id of the view
 ---
---- @example
---- ```lua
+--- @usage
 --- web.search.previous() -- Previous search result in current view
 --- web.search.previous(5) -- Previous search result in view id 5
---- ```
 function web.search.previous(view_id) return __internals.search_previous(view_id) end
 
 --- TODO: Document
@@ -348,19 +315,19 @@ function web.view.scroll_to_top(view_id) return __internals.view_scroll_to_top(v
 --- TODO: Document
 function web.view.scroll_to_bottom(view_id) return __internals.view_scroll_to_bottom(view_id) end
 
---- Decoration api
----
 --- @class DecorationOpts
 --- @field win? number
----
+
 --- @class Decoration
 --- @field enable fun(opts?: DecorationOpts): nil
 --- @field disable fun(opts?: DecorationOpts): nil
 --- @field set_enabled fun(enabled: boolean, opts?: DecorationOpts): nil
 --- @field is_enabled fun(opts?: DecorationOpts): boolean
 --- @field view fun(opts?: DecorationOpts): number|nil
----
---- @alias DecorationType number
+
+--- @class DecorationType: number
+
+--- Decoration api
 ---
 --- @param type DecorationType
 --- @return Decoration
@@ -381,12 +348,10 @@ local function create_decoration_api(type)
   }
 end
 
---- @see DecorationType in ./src/widgets/Decorations.hpp
+--- Maps to values defined in ./src/widgets/Decorations.hpp
 local DecorationType = { top = 1, bottom = 2, left = 3, right = 4 }
 
 web.decorations.top = create_decoration_api(DecorationType.top)
 web.decorations.bottom = create_decoration_api(DecorationType.bottom)
 web.decorations.left = create_decoration_api(DecorationType.left)
 web.decorations.right = create_decoration_api(DecorationType.right)
-
-print("api loaded")
diff --git a/lua/null-browser/extras/tabline.lua b/lua/null-browser/extras/tabline.lua
index e265940..9c53f41 100644
--- a/lua/null-browser/extras/tabline.lua
+++ b/lua/null-browser/extras/tabline.lua
@@ -72,6 +72,9 @@ function tabline.css()
       align-items: stretch;
       height: 100vh;
     }
+    .tabs.vertical {
+      flex-direction: column;
+    }
     .tab {
       all: unset;
       flex: 1;
diff --git a/lua/null-browser/utils.lua b/lua/null-browser/utils.lua
index 13b9d13..77ed60f 100644
--- a/lua/null-browser/utils.lua
+++ b/lua/null-browser/utils.lua
@@ -1,37 +1,46 @@
---- @type table
+--- Helper lua utils for null browser
+--- @module web
+
 _G.web = _G.web or {}
 web.utils = web.utils or {}
 
---- luv api
---- @type table
---- @link https://github.com/luvit/luv/blob/master/docs.md
+--- luv api (https://github.com/luvit/luv/blob/master/docs.md)
+---
 --- @diagnostic disable-next-line: undefined-global
 web.uv = web.uv or nil
 
 local inspector = require 'null-browser.inspect'
 
---- Returns human-readable string representation of Lua tables
----
---- @link https://github.com/kikito/inspect.lua
+--- Returns human-readable string representation of Lua tables (https://github.com/kikito/inspect.lua)
+--- @diagnostic disable-next-line: undefined-doc-param
+--- @param value any
+--- @return string
 web.inspect = inspector.inspect
 
--- TODO: Documentation
+--- Trim whitespace from start and end of a string
+--- @param str string
+--- @return string
 function web.utils.string_trim(str)
   local res, _ = string.gsub(str, '^%s*(.-)%s*$', '%1')
   return res
 end
 
--- TODO: Documentation
-function web.utils.table_merge(t, ...)
+--- Merge multiple tables
+--- @param tbl table
+--- @return table
+function web.utils.table_merge(tbl, ...)
   for i = 1, select("#", ...) do
     for k, v in pairs(select(i, ...) or {}) do
-      t[k] = v
+      tbl[k] = v
     end
   end
 
-  return t
+  return tbl
 end
 
+--- Get keys of a table
+--- @param tbl table
+--- @return table
 function web.utils.table_keys(tbl)
   local keys = {}
   for key, _ in pairs(tbl) do
@@ -63,6 +72,10 @@ local function is_deep_equal_helper(a, b, table_pairs)
   return a == b
 end
 
+--- Check if 2 values are deeply equal
+--- @param a any
+--- @param b any
+--- @return boolean
 function web.utils.equals(a, b)
   return is_deep_equal_helper(a, b, {})
 end