From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id ABA933858C78 for ; Thu, 18 Apr 2024 16:21:18 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org ABA933858C78 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org ABA933858C78 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713457281; cv=none; b=ZhUHa6Vl/cYrHx15svLh82YBLLBKCr8Lxz537YN765VY8lgxhaDPlvCuH8s7LtfRuCas0puUs+g6TadeVMct03ZKWx0EFZTaFzWks8Tsy1hBHjDCMFgBQwfp4BvbyEgNJXM4nsKGnmaxcubOfJjSWJgQFDmTZGlitZ0Y9Z9Eo38= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713457281; c=relaxed/simple; bh=8W4FU1GYETy1D1wieQHcnwK5zwbxxXycgTfIJMpkukw=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=HAcr/WaUPcRha+XjMjl1zvZDIwe29AHgiTH0yOPQ9xiLr5IoENVCz17q1ZH0sDuyDxVTtImDP5/NMp8XetRdxEFaQcvTtFwveh4+auRLN388JarCiPMaU+6+m0x9kSVaFOz66nTNVT2xCGjvF5rVBYlyZWAPfBQJ8DJ+KgKO01I= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1713457278; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type; bh=378xPqjQnMs13VDHbTw1OTSlBMNFxiiUd6vXL9X/kQs=; b=V6+X5tj4YNoKO5e2LyYZ+FHAT6JFgFb9PAPBoB+Q71j9YvHVXnVmLt0HkkDyvdk2+AAhvE dWcukfqfENEfxPA47TJMfiCZESiWQHmiks4U7i55HBcoJtWfXf+NXAFDvvyEaNMMe7ap86 V+4zhrtWvuLKkfjU3pFOoY+R0AZVvsE= Received: from mail-qk1-f199.google.com (mail-qk1-f199.google.com [209.85.222.199]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-382-KequwPcZOIC8BoIGc1NHrw-1; Thu, 18 Apr 2024 12:21:17 -0400 X-MC-Unique: KequwPcZOIC8BoIGc1NHrw-1 Received: by mail-qk1-f199.google.com with SMTP id af79cd13be357-78ed22211c4so160893985a.1 for ; Thu, 18 Apr 2024 09:21:17 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1713457276; x=1714062076; h=mime-version:user-agent:message-id:date:organization:subject:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=378xPqjQnMs13VDHbTw1OTSlBMNFxiiUd6vXL9X/kQs=; b=nSH2qnv958LAEjVGXcSk9/uIFfffl0xRPpMx4deKuHE+PVH356qdhptWxI3mC6Gj6F Nqmlal7AeWzDe1mF6GbNJ/mWw4sJ+H59/73EbYJPMdTwI8/YYjHVqujAbZ1/PWQ6QcFA ibDksRr+OkjHBcmpOpPnmnl/EPLZY0d6y4IBw5j4f+lO88nqscy6qLugOt30T2SY+Tco lE3Bz+Z6Hy9KB9esq1+6SodXfAsXvLcRoiJvAKKUr9hOkGR13m9XFnAYC9/AlvsR/cab IIUdf+XtGWCQe/n0sdIus/xnHOBNbpFSSjEd/Fl8im+1XW6Nt47rwZz4/ddRakAwgIo3 xexA== X-Gm-Message-State: AOJu0Yz0JKj1nZD1VkDe1v7oq5HgI5xKJ7vkDSW9Y/tOV17ft06/+YGN 0rJMUzQNDZIlgx7N8A+UjvFmPDTT3v2MEvsL1FQLoTlgYaotQ/THQMyZuEgXsXsVPFNmE3Zvalc xD44xz8dCbQgCDksp4Q4vilWnQAmE1xvaiyYqi+jYXt2OAq+TPDKEMZN7ExGjuBba/CA9+3tv3k 0fYdRyOYwo+fr67n+tIYOdBRcAMl1t/Ev3pUV4xw== X-Received: by 2002:a05:620a:568:b0:78f:fda:713f with SMTP id p8-20020a05620a056800b0078f0fda713fmr1997993qkp.10.1713457276532; Thu, 18 Apr 2024 09:21:16 -0700 (PDT) X-Google-Smtp-Source: AGHT+IFT7OWzCapYkja8L+YYFOv/RQLpPDCTDBJyJX1Y5XEFdZ/Nls+Ze4RXKW11/EBRwJ3cUEB8OQ== X-Received: by 2002:a05:620a:568:b0:78f:fda:713f with SMTP id p8-20020a05620a056800b0078f0fda713fmr1997955qkp.10.1713457276022; Thu, 18 Apr 2024 09:21:16 -0700 (PDT) Received: from localhost (88-120-130-27.subs.proxad.net. [88.120.130.27]) by smtp.gmail.com with ESMTPSA id o15-20020a05620a0d4f00b0078ee090baa3sm757273qkl.10.2024.04.18.09.21.15 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 18 Apr 2024 09:21:15 -0700 (PDT) Received: by localhost (Postfix, from userid 1000) id 16E3D5077C43; Thu, 18 Apr 2024 18:21:14 +0200 (CEST) From: Dodji Seketeli To: libabigail@sourceware.org Subject: [PATCH, applied] {ctf,btf}-reader: Document the namespace for nicer apidoc Organization: Red Hat / France X-Operating-System: AlmaLinux 9.3 X-URL: http://www.redhat.com Date: Thu, 18 Apr 2024 18:21:14 +0200 Message-ID: <87ttjyhcat.fsf@redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain X-Spam-Status: No, score=-12.3 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H4,RCVD_IN_MSPIKE_WL,RCVD_IN_SORBS_WEB,SPF_HELO_NONE,SPF_NONE,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: 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 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(-) diff --git a/include/abg-btf-reader.h b/include/abg-btf-reader.h index 9239d4f2..e891f268 100644 --- a/include/abg-btf-reader.h +++ b/include/abg-btf-reader.h @@ -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& 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& debug_info_root_paths, + environment& env, + bool load_all_types = false, + bool linux_kernel_mode = false); }//end namespace btf }//end namespace abigail diff --git a/include/abg-ctf-reader.h b/include/abg-ctf-reader.h index 58d1bc77..cd9e2dfe 100644 --- a/include/abg-ctf-reader.h +++ b/include/abg-ctf-reader.h @@ -23,6 +23,8 @@ namespace abigail { + +/// Namespace of the reader for the CTF debug information. namespace ctf { diff --git a/src/abg-btf-reader.cc b/src/abg-btf-reader.cc index 25fcb685..ac47c2ad 100644 --- a/src/abg-btf-reader.cc +++ b/src/abg-btf-reader.cc @@ -35,6 +35,7 @@ namespace abigail { using namespace ir; +/// Namespace of the reader for the BTF debug information. namespace btf { diff --git a/src/abg-ctf-reader.cc b/src/abg-ctf-reader.cc index cc3d2694..a377423a 100644 --- a/src/abg-ctf-reader.cc +++ b/src/abg-ctf-reader.cc @@ -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& 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, -- 2.39.3 -- Dodji