Tweak api docs

Author: kristijanhusak

lua/orgmode/api/file.lua

@@ -1,23 +1,23 @@
 local OrgHeadline = require('orgmode.api.headline')
 
 ---@class OrgFile
----@field category string current file category name. By default only filename without extension unless defined via #+CATEGORY directive
+---@field category string current file category name. By default it's only filename without extension unless defined differently via #+CATEGORY directive
 ---@field filename string absolute path of the current file
 ---@field headlines OrgHeadline[]
 ---@field is_archive_file boolean
----@field private file File
+---@field private _file File
 local OrgFile = {}
 
 ---@param headline OrgHeadline
 ---@param headlines_by_id table<string, OrgHeadline>
 ---@private
 local function map_child_headlines(headline, headlines_by_id)
-  if #headline.section.sections == 0 then
+  if #headline._section.sections == 0 then
     return headline
   end
 
   local child_headlines = {}
-  for _, child_section in ipairs(headline.section.sections) do
+  for _, child_section in ipairs(headline._section.sections) do
     local child_headline = headlines_by_id[child_section.id]
     child_headline.parent = headline
     table.insert(child_headlines, child_headline)
@@ -34,7 +34,7 @@ function OrgFile:_new(opts)
   data.filename = opts.filename
   data.headlines = opts.headlines
   data.is_archive_file = opts.is_archive_file or false
-  data.file = opts.file
+  data._file = opts._file
   setmetatable(data, self)
   self.__index = self
   return data
@@ -52,7 +52,7 @@ function OrgFile._build_from_internal_file(file)
   end
 
   local instance = OrgFile:_new({
-    file = file,
+    _file = file,
     category = file.category,
     filename = file.filename,
     headlines = headlines,
@@ -70,7 +70,7 @@ end
 --- Return refreshed instance of the file
 ---@return OrgFile
 function OrgFile:reload()
-  return OrgFile._build_from_internal_file(self.file:refresh())
+  return OrgFile._build_from_internal_file(self._file:refresh())
 end
 
 return OrgFile

lua/orgmode/api/headline.lua

@@ -22,8 +22,8 @@ local Calendar = require('orgmode.objects.calendar')
 ---@field parent OrgHeadline|nil
 ---@field priority string|nil
 ---@field headlines OrgHeadline[]
----@field private section Section
----@field private index number
+---@field private _section Section
+---@field private _index number
 local OrgHeadline = {}
 
 ---@private
@@ -45,8 +45,8 @@ function OrgHeadline:_new(opts)
   data.dates = opts.dates
   data.parent = opts.parent
   data.headlines = opts.headlines or {}
-  data.section = opts.section
-  data.index = opts.index
+  data._section = opts._section
+  data._index = opts._index
 
   setmetatable(data, self)
   self.__index = self
@@ -72,16 +72,16 @@ function OrgHeadline._build_from_internal_section(section, index)
       return date:is_none()
     end, section.dates),
     priority = section.priority,
-    section = section,
-    index = index,
+    _section = section,
+    _index = index,
   })
 end
 
 --- Return updated version of headline
 ---@return OrgHeadline
 function OrgHeadline:reload()
   local file = self.file:reload()
-  return file.headlines[self.index]
+  return file.headlines[self._index]
 end
 
 --- Set tags on the headline. This replaces all current tags with provided ones

lua/orgmode/api/init.lua

@@ -34,6 +34,7 @@ function OrgApi.load(name)
 
     return list
   end
+  error('Invalid argument to OrgApi.load')
 end
 
 --- Get current org buffer file