[applied] {ctf,btf}-reader: Document the namespace for nicer apidoc
Commit Message
Hello,
The apidoc is not generating any documentation for the libabigail::btf
and libabigail::ctf namespaces.
It turns out I need to add some doxygen comment to the these namespaces
in the source code. Fixed thus.
* include/abg-btf-reader.h (namespace btf): Add doxygen comment.
Just adding it to the *.cc won't cut it, I am not sure why.
* include/abg-ctf-reader.h (namespace ctf): Likewise.
* src/abg-btf-reader.cc (namespace btf): Add doxygen comment.
* src/abg-ctf-reader.cc (namespace ctf): Add doxygen commit.
(create_reader, reset_reader): Fix doxygen comments.
Signed-off-by: Dodji Seketeli <dodji@redhat.com>
Applied to the master branch.
---
include/abg-btf-reader.h | 45 ++++++++++++++++++++++++++++++++++------
include/abg-ctf-reader.h | 2 ++
src/abg-btf-reader.cc | 1 +
src/abg-ctf-reader.cc | 18 +++++++---------
4 files changed, 49 insertions(+), 17 deletions(-)
@@ -18,15 +18,48 @@
namespace abigail
{
+/// Namespace of the reader for the BTF debug information.
namespace btf
{
-elf_based_reader_sptr
-create_reader(const std::string& elf_path,
- const vector<char**>& debug_info_root_paths,
- environment& env,
- bool load_all_types = false,
- bool linux_kernel_mode = false);
+ /// Create and return a BTF reader (or front-end) which is an instance
+ /// of @ref btf::reader.
+ ///
+ /// @param elf_path the path to the path to the elf file the reader is
+ /// to be used for.
+ ///
+ /// @param debug_info_root_paths a vector to the paths to the
+ /// directories under which the debug info is to be found for @p
+ /// elf_path. Pass an empty vector if th debug info is not in a split
+ /// file.
+ ///
+ /// @param environment the environment used by the current context.
+ /// This environment contains resources needed by the BTF reader and
+ /// by the types and declarations that are to be created later. Note
+ /// that ABI artifacts that are to be compared all need to be created
+ /// within the same environment.
+ ///
+ /// Please also note that the life time of this environment object
+ /// must be greater than the life time of the resulting @ref
+ /// reader the context uses resources that are allocated in the
+ /// environment.
+ ///
+ /// @param load_all_types if set to false only the types that are
+ /// reachable from publicly exported declarations (of functions and
+ /// variables) are read. If set to true then all types found in the
+ /// debug information are loaded.
+ ///
+ /// @param linux_kernel_mode if set to true, then consider the special
+ /// linux kernel symbol tables when determining if a symbol is
+ /// exported or not.
+ ///
+ /// @return a smart pointer to the resulting btf::reader.
+ elf_based_reader_sptr
+ create_reader(const std::string& elf_path,
+ const vector<char**>& debug_info_root_paths,
+ environment& env,
+ bool load_all_types = false,
+ bool linux_kernel_mode = false);
}//end namespace btf
}//end namespace abigail
@@ -23,6 +23,8 @@
namespace abigail
{
+
+/// Namespace of the reader for the CTF debug information.
namespace ctf
{
@@ -35,6 +35,7 @@ namespace abigail
{
using namespace ir;
+/// Namespace of the reader for the BTF debug information.
namespace btf
{
@@ -42,6 +42,7 @@ ABG_END_EXPORT_DECLARATIONS
namespace abigail
{
+/// Namespace of the reader for the CTF debug information
namespace ctf
{
using std::dynamic_pointer_cast;
@@ -1671,8 +1672,11 @@ fill_ctf_section(const Elf_Scn *elf_section, ctf_sect_t *ctf_section)
/// from a given ELF file.
///
/// @param elf_path the patch of some ELF file.
+///
+/// @param debug_info_root_paths the paths to where to find the debug
+/// info.
+///
/// @param env a libabigail IR environment.
-
elf_based_reader_sptr
create_reader(const std::string& elf_path,
const vector<char**>& debug_info_root_paths,
@@ -1692,16 +1696,8 @@ create_reader(const std::string& elf_path,
/// @param elf_path the path to the elf file the context is to be used
/// for.
///
-/// @param environment the environment used by the current context.
-/// This environment contains resources needed by the reader and by
-/// the types and declarations that are to be created later. Note
-/// that ABI artifacts that are to be compared all need to be created
-/// within the same environment.
-///
-/// Please also note that the life time of this environment object
-/// must be greater than the life time of the resulting @ref
-/// reader the context uses resources that are allocated in the
-/// environment.
+/// @param debug_info_root_paths the paths pointing to where to find
+/// the debug info.
void
reset_reader(elf_based_reader& rdr,
const std::string& elf_path,