local strict = require("strict")
 local tools = require("tools")
 
+--- Return_flags table. Provide build status info back to the caller.
+-- @table return_flags
+-- @field stop boolean: stop the build process
+-- @field message false or string with a message
+
+--- Build process class. Every result is given to an instance of this class.
+-- @type build_process_class
 e2build.build_process_class = class("build_process_class")
 
+---
 function e2build.build_process_class:initialize()
     self._modes = {}
 
 
 --- Add build step after specified.
 -- @param mode Build mode
--- @param before Add build step after this one
+-- @param after Add build step after this one
 -- @param name Name of build step
 -- @param func Method of build_process_class implementing the build step.
 function e2build.build_process_class:add_step_after(mode, after, name, func)
     table.insert(self._modes[mode], pos + 1, { name = name, func = func })
 end
 
+---
 function e2build.build_process_class:_next_step(mode)
     assertIsStringN(mode)
     assertIsTable(self._modes[mode])
 end
 
 --- check if a chroot exists for this result
--- @param info Info table
--- @param resultname Result name
+-- @param res Result object
+-- @param return_flags return_flags
 -- @return True if chroot for result could be found, false otherwise.
 function e2build.build_process_class:_chroot_exists(res, return_flags)
     local bc = res:build_config()
 end
 
 --- Enter playground.
--- @param info
--- @param resultname
--- @param chroot_command (optional)
+-- @param res Result object
+-- @param return_flags return_flags
 -- @return True on success, false on error.
 -- @return Error object on failure.
 function e2build.build_process_class:_enter_playground(res, return_flags)
 --- Return true if the result given in c is already available, false otherwise
 -- return the path to the result
 -- check if a result is already available
--- @param info
--- @param resultname string: result name
--- @param return_flags table: return values through this table
+-- @param res Result object
+-- @param return_flags return_flags
 -- @return bool
 -- @return an error object on failure
 function e2build.build_process_class:_result_available(res, return_flags)
     return true
 end
 
---- TODO
+---
 function e2build.build_process_class:_chroot_lock(res, return_flags)
     local rc, re, bc
     local e = err.new("error locking chroot")
     return true
 end
 
+---
 function e2build.build_process_class:helper_chroot_remove(res)
     local e = err.new("removing chroot failed")
     local rc, re, bc
     return true
 end
 
+---
 function e2build.build_process_class:_chroot_cleanup_if_exists(res, return_flags)
     local rc, re
 
     return true
 end
 
---- TODO
+---
 function e2build.build_process_class:_setup_chroot(res, return_flags)
     local rc, re, bc, info
     local e = err.new("error setting up chroot")
     return true
 end
 
+---
 function e2build.build_process_class:_install_directory_structure(res, return_flags)
     local rc, re, e, bc, dirs
     bc = res:build_config()
     return true
 end
 
+---
 function e2build.build_process_class:_install_build_script(res, return_flags)
     local rc, re, e, bc, location, destdir, info
     bc = res:build_config()
     return true
 end
 
+---
 function e2build.build_process_class:_install_env(res, return_flags)
     local rc, re, e, bc
     e = err.new("installing environment files failed")
     return true
 end
 
+---
 function e2build.build_process_class:_install_init_files(res, return_flags)
     local rc, re, info
     local bc = res:build_config()
     return true
 end
 
+---
 function e2build.build_process_class:_install_build_driver(res, return_flags)
     local e, rc, re
     local bc, bd, destdir, buildrc_noinit_file, info, buildrc_file
     return true
 end
 
+---
 function e2build.build_process_class:helper_unpack_result(res, dep, destdir)
     local rc, re, e
     local info, buildid, server, location, resulttarpath, tmpdir
     return true
 end
 
+---
 function e2build.build_process_class:_install_build_time_dependencies(res, return_flags)
     local e, rc, re
     local dependslist, info, dep, destdir
     return true
 end
 
+---
 function e2build.build_process_class:_install_sources(res, return_flags)
     local rc, re, e, bc, destdir, source_set, info
 
     return true
 end
 
---- TODO
+---
 function e2build.build_process_class:_fix_permissions(res, return_flags)
     local rc, re, bc
     local e = err.new("fixing permissions failed")
     return true
 end
 
---- TODO
+---
 function e2build.build_process_class:_build_playground(res, return_flags)
 
     if res:build_settings():prep_playground()  then
     return true
 end
 
---- TODO
+---
 function e2build.build_process_class:_runbuild(res, return_flags)
     local rc, re, out, bc
     local e = err.new("build failed")
     return true
 end
 
---- TODO
+---
 function e2build.build_process_class:_linklast(res, return_flags)
     local rc, re, e
     local info, server, location, buildid, dst, lnk
     return true
 end
 
---- TODO
+---
 function e2build.build_process_class:_chroot_cleanup(res, return_flags)
     local rc, re
     -- do not remove chroot if the user requests to keep it
     return true
 end
 
+---
 function e2build.build_process_class:_chroot_unlock(res, return_flags)
     local rc, re, bc
     local e = err.new("error unlocking chroot")
 end
 
 --------------------------------------------------------------------------------
+--- Base class for settings provided to the build process
+-- @type settings_class
 e2build.settings_class = class("settings")
 
+---
 function e2build.settings_class:mode()
     error("called settings_class:mode() of base class")
 end
 
 --------------------------------------------------------------------------------
+--- Build Settings class.
+-- @type build_settings_class
 e2build.build_settings_class = class("build_settings", e2build.settings_class)
 
+---
 function e2build.build_settings_class:initialize()
         self._selected = false
         self._force_rebuild = false
     return "build"
 end
 
+---
 function e2build.build_settings_class:selected(value)
     if value then
         assertIsBoolean(value)
     return self._selected
 end
 
+---
 function e2build.build_settings_class:force_rebuild(value)
     if value then
         assertIsBoolean(value)
     return self._force_rebuild
 end
 
+---
 function e2build.build_settings_class:keep_chroot(value)
     if value then
         assertIsBoolean(value)
     return self._keep_chroot
 end
 
+---
 function e2build.build_settings_class:prep_playground(value)
     if value then
         assertIsBoolean(value)
 end
 
 --------------------------------------------------------------------------------
+--- Playground Settings class.
+-- @type playground_settings_class
 e2build.playground_settings_class = class("playground_settings", e2build.settings_class)
 
+---
 function e2build.playground_settings_class:initialize()
     self._profile = false
     self._command = false
     return "playground"
 end
 
+---
 function e2build.playground_settings_class:profile(value)
     if value then
         assertIsString(value)
     return self._profile
 end
 
+---
 function e2build.playground_settings_class:command(value)
     if value then
         assertIsString(value)