Add docs

docs/doxygen.cfg

@@ -872,7 +872,6 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = lsplt/src/main/jni/include/lsplt.hpp \
-                         docs/jni.h \
                          README.md
 
 # This tag can be used to specify the character encoding of the source files

lsplt/src/main/jni/include/lsplt.hpp

@@ -5,27 +5,83 @@
 #include <string>
 #include <string_view>
 
+/// \namespace namespace of LSPlt
 namespace lsplt {
 inline namespace v1 {
 
+/// \struct MapInfo
+/// \brief An entry that describes a line in /proc/self/maps. You can obtain a list of these entries
+/// by calling #Scan().
 struct MapInfo {
+    /// \brief The start address of the memory region.
     uintptr_t start;
+    /// \brief The end address of the memory region.
     uintptr_t end;
+    /// \brief The permissions of the memory region. This is a bit mask of the following values:
+    /// - PROT_READ
+    /// - PROT_WRITE
+    /// - PROT_EXEC
     uint8_t perms;
+    /// \brief Whether the memory region is private.
     bool is_private;
+    /// \brief The offset of the memory region.
     uintptr_t offset;
+    /// \brief The device number of the memory region.
+    /// Major can be obtained by #major()
+    /// Minor can be obtained by #minor()
     dev_t dev;
+    /// \brief The inode number of the memory region.
     ino_t inode;
+    /// \brief The path of the memory region.
     std::string path;
 
+    /// \brief Scans /proc/self/maps and returns a list of \ref MapInfo entries.
+    /// This is useful to find out the inode of the library to hook.
+    /// \return A list of \ref MapInfo entries.
     [[maybe_unused, gnu::visibility("default")]] static std::vector<MapInfo> Scan();
 };
 
-[[maybe_unused, gnu::visibility("default")]] bool RegisterHook(ino_t ino, std::string_view symbol,
+/// \brief Register a hook to a function.
+/// \param inode The inode of the library to hook. You can obtain the inode by #stat() or by finding
+/// the library in the list returned by #MapInfo::Scan().
+/// \param symbol The function symbol to hook.
+/// \param callback The callback function pointer to call when the function is called.
+/// \param backup The backup function pointer which can call the original function. This is optional.
+/// \return Whether the hook is successfully registered.
+/// \note This function is thread-safe.
+/// \note \p backup will not be available until #CommitHook() is called.
+/// \note \p backup will be nullptr if the hook fails.
+/// \note You can unhook the function by calling this function with \p callback set to the backup
+/// set by previous call.
+/// \note LSPlt will backup the hook memory region and restore it when the hook is restored
+/// to its original function pointer so that there won't be dirty pages.
+/// LSPlt will do hooks on a copied memory region so that the original memory region will not be
+/// modified. You can invalidate this behaviour and hook the original memory region by calling
+/// #InvalidateBackup().
+/// \see #CommitHook()
+/// \see #InvalidateBackup()
+[[maybe_unused, gnu::visibility("default")]] bool RegisterHook(ino_t inode, std::string_view symbol,
                                                                void *callback, void **backup);
 
+/// \brief Commit all registered hooks.
+/// \return Whether all hooks are successfully committed. If any of the hooks fail to commit,
+/// the result is false.
+/// \note This function is thread-safe.
+/// \note The return value indicates whether all hooks are successfully committed. You can
+/// determine which hook fails by checking the backup function pointer of #RegisterHook().
+/// \see #RegisterHook()
 [[maybe_unused, gnu::visibility("default")]] bool CommitHook();
 
+/// \brief Invalidate backup memory regions
+/// Normally LSPlt will backup the hooked memory region and do hook on a copied anonymous memory
+/// region, and restore the original memory region when the hook is unregistered
+/// (when the callback of #RegisterHook() is the original function). This function will restore
+/// the backup memory region and do all existing hooks on the original memory region.
+/// \return Whether all hooks are successfully invalidated. If any of the hooks fail to invalidate,
+/// the result is false.
+/// \note This function is thread-safe.
+/// \note This will be automatically called when the library is unloaded.
+/// \see #RegisterHook()
 [[maybe_unused, gnu::visibility("default")]] bool InvalidateBackup();
 }  // namespace v1
 }  // namespace lsplt