ircd::mods: Improve path translation for symbols() suite; add comments.

include/ircd/mods/mapi.h

@@ -37,6 +37,7 @@ namespace ircd::mapi
 		"IRCD_MODULE"
 	};
 
+	/// Symbols in this section are automatically demangle-mapped on load.
 	const char *const import_section_name
 	{
 		IRCD_MODULE_EXPORT_SECTION
@@ -57,6 +58,13 @@ IRCD_MAPI_VERSION
 	4
 };
 
+/// Module Header
+///
+/// A static instance of this class must be included in an IRCd module with
+/// the unmangled name of IRCD_MODULE (thus there can be only one). It must
+/// be externally visible. If this is not present or not visible, ircd::mods
+/// will not consider the file to be an IRCd module and it will be ignored.
+///
 struct ircd::mapi::header
 {
 	const magic_t magic {IRCD_MAPI_MAGIC};       // The magic must match

include/ircd/mods/paths.h

@@ -21,6 +21,10 @@ namespace ircd::mods
 	std::string prefix_if_relative(std::string);
 }
 
+/// Search paths vector for modules. These directories will be searched
+/// when a relative path/name is given to various other places in the
+/// ircd::mods interface.
+///
 struct ircd::mods::paths
 :std::vector<std::string>
 {

include/ircd/mods/symbols.h

@@ -11,19 +11,28 @@
 #pragma once
 #define HAVE_IRCD_MODS_SYMBOLS_H
 
+// Section & Symbol utilites
+//
+// All path parameters can be absolute paths to any module file, or relative
+// names which will be found using the mods::paths system.
+
 namespace ircd::mods
 {
-	// Section & Symbol utilites
-	std::vector<std::string> sections(const string_view &fullpath);
+	// Get all section names
+	std::vector<std::string> sections(const string_view &path);
 
-	std::vector<std::string> symbols(const string_view &fullpath, const string_view &section);
-	std::vector<std::string> symbols(const string_view &fullpath);
+	// Get all symbol names (mangled)
+	std::vector<std::string> symbols(const string_view &path, const string_view &section);
+	std::vector<std::string> symbols(const string_view &path);
 
+	// Generate demangled -> mangled map
 	std::map<std::string, std::string> mangles(const std::vector<std::string> &);
-	std::map<std::string, std::string> mangles(const string_view &fullpath, const string_view &section);
-	std::map<std::string, std::string> mangles(const string_view &fullpath);
+	std::map<std::string, std::string> mangles(const string_view &path, const string_view &section);
+	std::map<std::string, std::string> mangles(const string_view &path);
 
-	// Find module names where symbol resides
+	// Test if module has (mangled) symbol (optionally in section)
 	bool has_symbol(const string_view &name, const string_view &symbol, const string_view &section = {});
+
+	// Find module names where (mangled) symbol resides in the mods::paths
 	std::vector<std::string> find_symbol(const string_view &symbol, const string_view &section = {});
 }

ircd/mods.cc

@@ -907,17 +907,12 @@ ircd::mods::has_symbol(const string_view &name,
                        const string_view &symbol,
                        const string_view &section)
 {
-	const auto path
-	{
-		fullpath(name)
-	};
-
-	if(path.empty())
+	if(name.empty() || symbol.empty())
 		return false;
 
 	const auto syms
 	{
-		symbols(path, section)
+		symbols(name, section)
 	};
 
 	return std::find(begin(syms), end(syms), symbol) != end(syms);
@@ -989,13 +984,20 @@ ircd::mods::sections(const string_view &path)
 template<class R,
          class F>
 R
-ircd::mods::info(const string_view &path,
+ircd::mods::info(const string_view &p,
                  F&& closure)
 try
 {
+	const auto path
+	{
+		fs::is_relative(p)?
+			fs::_path(fullpath(p)):
+			fs::_path(p)
+	};
+
 	boost::dll::library_info info
 	{
-		fs::_path(path)
+		path
 	};
 
 	return closure(info);
@@ -1004,7 +1006,7 @@ catch(const filesystem::filesystem_error &e)
 {
 	throw fs::error
 	{
-		e, "%s", path
+		e, "%s", p
 	};
 }