From: Arnaud Giersch Date: Thu, 24 Jun 2021 18:26:20 +0000 (+0200) Subject: Fix a few warnings when building doc (mostly related to doxygen). X-Git-Tag: v3.28~58 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/8206f2d5427004aa113da1f9985d9263183bb978 Fix a few warnings when building doc (mostly related to doxygen). --- diff --git a/docs/source/Doxyfile b/docs/source/Doxyfile index a6fe764d3a..cf7246a880 100644 --- a/docs/source/Doxyfile +++ b/docs/source/Doxyfile @@ -1,6 +1,7 @@ # What to read INPUT = ../../include/simgrid/forward.h -INPUT += ../../include/simgrid/s4u +INPUT += ../../include/simgrid/plugins/ +INPUT += ../../include/simgrid/s4u/ INPUT += ../../include/simgrid/msg.h INPUT += ../../include/simgrid/actor.h INPUT += ../../src/s4u/s4u_Actor.cpp @@ -9,6 +10,7 @@ INPUT += ../../include/simgrid/cond.h INPUT += ../../include/simgrid/engine.h INPUT += ../../include/simgrid/exec.h INPUT += ../../include/simgrid/host.h +INPUT += ../../src/s4u/s4u_Host.cpp #INPUT += ../../include/simgrid/instr.h INPUT += ../../include/simgrid/link.h INPUT += ../../include/simgrid/mailbox.h @@ -52,6 +54,7 @@ PREDEFINED += \ DOXYGEN \ SG_BEGIN_DECL= \ SG_END_DECL= \ + SIMGRID_REGISTER_PLUGIN(id,desc,init)= \ XBT_PUBLIC= \ XBT_EXPORT_NO_IMPORT= \ XBT_IMPORT_NO_EXPORT= \ @@ -62,8 +65,8 @@ PREDEFINED += \ XBT_PRIVATE= \ XBT_ATTRIB_NORETURN= \ XBT_ATTRIB_UNUSED= \ - XBT_LOG_NEW_DEFAULT_SUBCATEGORY(s,c,l)= \ - XBT_ATTRIB_DEPRECATED_v329(m)= \ - XBT_ATTRIB_DEPRECATED_v330(m)= \ - XBT_ATTRIB_DEPRECATED_v331(m)= \ - XBT_ATTRIB_DEPRECATED_v332(m)= + XBT_LOG_NEW_DEFAULT_SUBCATEGORY(cname,parent,desc)= \ + XBT_ATTRIB_DEPRECATED_v329(mesg)= \ + XBT_ATTRIB_DEPRECATED_v330(mesg)= \ + XBT_ATTRIB_DEPRECATED_v331(mesg)= \ + XBT_ATTRIB_DEPRECATED_v332(mesg)= diff --git a/docs/source/XML_reference.rst b/docs/source/XML_reference.rst index fbfe9a72b6..08290d99c3 100644 --- a/docs/source/XML_reference.rst +++ b/docs/source/XML_reference.rst @@ -447,7 +447,7 @@ elements such as host or peer) |br| .. _pf_tag_zoneRoute: ------- +----------- The purpose of this entity is to define a route between two zones. Recall that all zones form a tree, so to connect two sibling zones, diff --git a/include/simgrid/s4u/ConditionVariable.hpp b/include/simgrid/s4u/ConditionVariable.hpp index 184c4c989f..793c47c55d 100644 --- a/include/simgrid/s4u/ConditionVariable.hpp +++ b/include/simgrid/s4u/ConditionVariable.hpp @@ -26,8 +26,10 @@ namespace s4u { */ class XBT_PUBLIC ConditionVariable { private: +#ifndef DOXYGEN friend kernel::activity::ConditionVariableImpl; friend void kernel::activity::intrusive_ptr_release(kernel::activity::ConditionVariableImpl* cond); +#endif kernel::activity::ConditionVariableImpl* const pimpl_; diff --git a/include/simgrid/s4u/Disk.hpp b/include/simgrid/s4u/Disk.hpp index 5f395d667e..8fbc6b54a7 100644 --- a/include/simgrid/s4u/Disk.hpp +++ b/include/simgrid/s4u/Disk.hpp @@ -30,9 +30,11 @@ namespace s4u { */ class XBT_PUBLIC Disk : public xbt::Extendable { +#ifndef DOXYGEN friend Engine; friend Io; friend kernel::resource::DiskImpl; +#endif explicit Disk(kernel::resource::DiskImpl* pimpl) : pimpl_(pimpl) {} virtual ~Disk() = default; diff --git a/include/simgrid/s4u/Engine.hpp b/include/simgrid/s4u/Engine.hpp index 1519dd9a86..7f43c2fe35 100644 --- a/include/simgrid/s4u/Engine.hpp +++ b/include/simgrid/s4u/Engine.hpp @@ -24,7 +24,9 @@ namespace s4u { * This is a singleton containing all the main functions of the simulation. */ class XBT_PUBLIC Engine { +#ifndef DOXYGEN friend simgrid::kernel::EngineImpl; +#endif public: /** Constructor, taking only the name of your main function */ @@ -145,8 +147,8 @@ public: /** * @brief Add a model to engine list * - * @param model Pointer to model - * @param list List of dependencies for this model (optional) + * @param model Pointer to model + * @param dependencies List of dependencies for this model (optional) */ void add_model(std::shared_ptr model, const std::vector& dependencies = {}); diff --git a/include/simgrid/s4u/Exec.hpp b/include/simgrid/s4u/Exec.hpp index ad8475a50c..c4ac5542d8 100644 --- a/include/simgrid/s4u/Exec.hpp +++ b/include/simgrid/s4u/Exec.hpp @@ -30,7 +30,10 @@ namespace s4u { * @endrst */ class XBT_PUBLIC Exec : public Activity_T { +#ifndef DOXYGEN friend kernel::activity::ExecImpl; +#endif + bool parallel_ = false; protected: @@ -55,10 +58,12 @@ public: /*! Same as wait_any, but with a timeout. If the timeout occurs, parameter last is returned.*/ static ssize_t wait_any_for(const std::vector& execs, double timeout); +#ifndef DOXYGEN XBT_ATTRIB_DEPRECATED_v332("Please use a plain vector for parameter") static int wait_any(std::vector* execs) { return static_cast(wait_any_for(*execs, -1)); } XBT_ATTRIB_DEPRECATED_v332("Please use a plain vector for first parameter") static int wait_any_for(std::vector* execs, double timeout) { return static_cast(wait_any_for(*execs, timeout)); } +#endif /** @brief On sequential executions, returns the amount of flops that remain to be done; This cannot be used on * parallel executions. */ @@ -73,7 +78,9 @@ public: ExecPtr set_bound(double bound); ExecPtr set_priority(double priority); +#ifndef DOXYGEN XBT_ATTRIB_DEPRECATED_v329("Please use exec_init(...)->wait_for(timeout)") ExecPtr set_timeout(double timeout); +#endif Host* get_host() const; unsigned int get_host_number() const; diff --git a/include/simgrid/s4u/Host.hpp b/include/simgrid/s4u/Host.hpp index 9bb95fa9c4..c39588fda3 100644 --- a/include/simgrid/s4u/Host.hpp +++ b/include/simgrid/s4u/Host.hpp @@ -136,7 +136,7 @@ public: * The amount of flops per second available for computing depends on several things: * - The current pstate determines the maximal peak computing speed (use @ref get_pstate_speed() to retrieve the * computing speed you would get at another pstate) - * - If you declared an external load (with @ref simgrid::surf::Cpu::set_speed_profile()), you must multiply the + * - If you declared an external load (with @ref set_speed_profile()), you must multiply the * result of get_speed() by get_available_speed() to retrieve what a new computation would get. * * The remaining speed is then shared between the executions located on this host. @@ -149,7 +149,7 @@ public: double get_speed() const; /** @brief Get the available speed ratio, between 0 and 1. * - * This accounts for external load (see @ref simgrid::surf::Cpu::set_speed_profile()). + * This accounts for external load (see @ref set_speed_profile()). */ double get_available_speed() const; @@ -199,9 +199,7 @@ public: #ifndef DOXYGEN XBT_ATTRIB_DEPRECATED_v331("Please use Comm::sendto()") void sendto(Host* dest, double byte_amount); - XBT_ATTRIB_DEPRECATED_v331("Please use Comm::sendto_async()") CommPtr sendto_async(Host* dest, double byte_amount); - XBT_ATTRIB_DEPRECATED_v330("Please use Host::sendto()") void send_to(Host* dest, double byte_amount); #endif diff --git a/include/simgrid/s4u/Io.hpp b/include/simgrid/s4u/Io.hpp index 2ed2ca8f1b..1e7825bddd 100644 --- a/include/simgrid/s4u/Io.hpp +++ b/include/simgrid/s4u/Io.hpp @@ -20,7 +20,9 @@ namespace s4u { */ class XBT_PUBLIC Io : public Activity_T { +#ifndef DOXYGEN friend kernel::activity::IoImpl; +#endif protected: explicit Io(kernel::activity::IoImplPtr pimpl); diff --git a/include/simgrid/s4u/Link.hpp b/include/simgrid/s4u/Link.hpp index 9297480190..b00085377c 100644 --- a/include/simgrid/s4u/Link.hpp +++ b/include/simgrid/s4u/Link.hpp @@ -30,7 +30,9 @@ namespace s4u { * @endrst */ class XBT_PUBLIC Link : public xbt::Extendable { +#ifndef DOXYGEN friend kernel::resource::LinkImpl; +#endif // Links are created from the NetZone, and destroyed by their private implementation when the simulation ends explicit Link(kernel::resource::LinkImpl* pimpl) : pimpl_(pimpl) {} diff --git a/include/simgrid/s4u/Mailbox.hpp b/include/simgrid/s4u/Mailbox.hpp index 4daf3752be..3fabf154d3 100644 --- a/include/simgrid/s4u/Mailbox.hpp +++ b/include/simgrid/s4u/Mailbox.hpp @@ -20,9 +20,11 @@ namespace s4u { /** @brief Mailboxes: Network rendez-vous points. */ class XBT_PUBLIC Mailbox { +#ifndef DOXYGEN friend Comm; friend smpi::Request; friend kernel::activity::MailboxImpl; +#endif kernel::activity::MailboxImpl* const pimpl_; @@ -111,18 +113,21 @@ public: /** Creates (but don't start) a data reception onto that mailbox */ CommPtr get_init(); /** Creates and start an async data reception to that mailbox */ - XBT_ATTRIB_DEPRECATED_v331("Please use typed template Mailbox::get_async<>()") CommPtr get_async(void** data); template CommPtr get_async(T** data); /** Blocking data reception */ template T* get(); - XBT_ATTRIB_DEPRECATED_v331("Please use typed template Mailbox::get<>()") void* get(); template std::unique_ptr get_unique() { return std::unique_ptr(get()); } /** Blocking data reception with timeout */ template T* get(double timeout); - XBT_ATTRIB_DEPRECATED_v331("Please use typed template Mailbox::get<>()") void* get(double timeout); template std::unique_ptr get_unique(double timeout) { return std::unique_ptr(get(timeout)); } + +#ifndef DOXYGEN + XBT_ATTRIB_DEPRECATED_v331("Please use typed template Mailbox::get_async<>()") CommPtr get_async(void** data); + XBT_ATTRIB_DEPRECATED_v331("Please use typed template Mailbox::get<>()") void* get(); + XBT_ATTRIB_DEPRECATED_v331("Please use typed template Mailbox::get<>()") void* get(double timeout); +#endif }; template CommPtr Mailbox::get_async(T** data) @@ -146,6 +151,7 @@ template T* Mailbox::get(double timeout) return res; } +#ifndef DOXYGEN inline CommPtr Mailbox::get_async(void** data) // XBT_ATTRIB_DEPRECATED_v331 { return get_async(data); @@ -158,7 +164,7 @@ inline void* Mailbox::get(double timeout) // XBT_ATTRIB_DEPRECATED_v331 { return get(timeout); } - +#endif } // namespace s4u } // namespace simgrid diff --git a/include/simgrid/s4u/Mutex.hpp b/include/simgrid/s4u/Mutex.hpp index 4f2c486e5c..87d47682a2 100644 --- a/include/simgrid/s4u/Mutex.hpp +++ b/include/simgrid/s4u/Mutex.hpp @@ -29,9 +29,11 @@ namespace s4u { * @endrst */ class XBT_PUBLIC Mutex { +#ifndef DOXYGEN friend ConditionVariable; friend kernel::activity::MutexImpl; friend void kernel::activity::intrusive_ptr_release(kernel::activity::MutexImpl* mutex); +#endif kernel::activity::MutexImpl* const pimpl_; /* refcounting */ diff --git a/include/simgrid/s4u/NetZone.hpp b/include/simgrid/s4u/NetZone.hpp index 9daaf7b750..ed6afa8d3c 100644 --- a/include/simgrid/s4u/NetZone.hpp +++ b/include/simgrid/s4u/NetZone.hpp @@ -27,11 +27,13 @@ namespace s4u { * s4u::Engine). */ class XBT_PUBLIC NetZone { +#ifndef DOXYGEN + friend kernel::routing::NetZoneImpl; +#endif + kernel::routing::NetZoneImpl* const pimpl_; protected: - friend kernel::routing::NetZoneImpl; - explicit NetZone(kernel::routing::NetZoneImpl* impl) : pimpl_(impl) {} public: @@ -76,17 +78,19 @@ public: * * @param src Source netzone's netpoint * @param dst Destination netzone' netpoint - * @param src_gw Netpoint of the gateway in the source netzone - * @param dst_gw Netpoint of the gateway in the destination netzone + * @param gw_src Netpoint of the gateway in the source netzone + * @param gw_dst Netpoint of the gateway in the destination netzone * @param link_list List of links used in this communication * @param symmetrical Bi-directional communication */ void add_route(kernel::routing::NetPoint* src, kernel::routing::NetPoint* dst, kernel::routing::NetPoint* gw_src, kernel::routing::NetPoint* gw_dst, const std::vector& link_list, bool symmetrical = true); +#ifndef DOXYGEN XBT_ATTRIB_DEPRECATED_v332("Please use add_route() method which uses s4u::Link instead of LinkImpl") void add_route( kernel::routing::NetPoint* src, kernel::routing::NetPoint* dst, kernel::routing::NetPoint* gw_src, kernel::routing::NetPoint* gw_dst, const std::vector& link_list, bool symmetrical); +#endif void add_bypass_route(kernel::routing::NetPoint* src, kernel::routing::NetPoint* dst, kernel::routing::NetPoint* gw_src, kernel::routing::NetPoint* gw_dst, std::vector& link_list, bool symmetrical); @@ -103,7 +107,7 @@ public: * @brief Create a host * * @param name Host name - * @param speed_per_state Vector of CPU's speeds + * @param speed_per_pstate Vector of CPU's speeds */ s4u::Host* create_host(const std::string& name, const std::vector& speed_per_pstate); s4u::Host* create_host(const std::string& name, double speed); diff --git a/include/simgrid/s4u/Semaphore.hpp b/include/simgrid/s4u/Semaphore.hpp index 159d0ac6f5..8520d61a94 100644 --- a/include/simgrid/s4u/Semaphore.hpp +++ b/include/simgrid/s4u/Semaphore.hpp @@ -29,8 +29,10 @@ namespace s4u { * */ class XBT_PUBLIC Semaphore { +#ifndef DOXYGEN friend kernel::activity::SemaphoreImpl; friend void kernel::activity::intrusive_ptr_release(kernel::activity::SemaphoreImpl* sem); +#endif kernel::activity::SemaphoreImpl* const pimpl_; diff --git a/src/plugins/file_system/s4u_FileSystem.cpp b/src/plugins/file_system/s4u_FileSystem.cpp index 12dd673424..d0c365c484 100644 --- a/src/plugins/file_system/s4u_FileSystem.cpp +++ b/src/plugins/file_system/s4u_FileSystem.cpp @@ -152,6 +152,7 @@ sg_size_t File::read(sg_size_t size) * @ingroup plugin_filesystem * * @param size of the file to write + * @param write_inside * @return the number of bytes successfully write or -1 if an error occurred */ sg_size_t File::write(sg_size_t size, bool write_inside) diff --git a/src/plugins/vm/VirtualMachineImpl.hpp b/src/plugins/vm/VirtualMachineImpl.hpp index d013face3a..68bd7c3b0c 100644 --- a/src/plugins/vm/VirtualMachineImpl.hpp +++ b/src/plugins/vm/VirtualMachineImpl.hpp @@ -28,7 +28,9 @@ namespace vm { * @details A VM represent a virtual machine */ class XBT_PUBLIC VirtualMachineImpl : public surf::HostImpl, public simgrid::xbt::Extendable { +#ifndef DOXYGEN friend simgrid::s4u::VirtualMachine; +#endif public: /** @brief Callbacks fired after VM creation. Signature: `void(VirtualMachineImpl&)` */ diff --git a/src/s4u/s4u_Host.cpp b/src/s4u/s4u_Host.cpp index b78f2cb37e..a843737cbe 100644 --- a/src/s4u/s4u_Host.cpp +++ b/src/s4u/s4u_Host.cpp @@ -38,6 +38,7 @@ Host* Host::set_cpu(kernel::resource::CpuImpl* cpu) return this; } +#ifndef DOXYGEN Host* Host::set_netpoint(kernel::routing::NetPoint* netpoint) { pimpl_netpoint_ = netpoint; @@ -50,6 +51,7 @@ Host::~Host() Engine::get_instance()->netpoint_unregister(pimpl_netpoint_); delete pimpl_cpu_; } +#endif /** @brief Fire the required callbacks and destroy the object * @@ -183,6 +185,7 @@ NetZone* Host::get_englobing_zone() const return pimpl_netpoint_->get_englobing_zone()->get_iface(); } +#ifndef DOXYGEN void Host::sendto(Host* dest, double byte_amount) // deprecated 331 { Comm::sendto_async(this, dest, byte_amount)->wait(); @@ -197,6 +200,7 @@ void Host::send_to(Host* dest, double byte_amount) // deprecated 330 { Comm::sendto(this, dest, byte_amount); } +#endif /** Get the properties assigned to a host */ const std::unordered_map* Host::get_properties() const @@ -486,7 +490,7 @@ double sg_host_speed(const_sg_host_t host) // XBT_ATTRIB_DEPRECATED_v330 return sg_host_get_speed(host); } -/** @brief Return the speed of the processor (in flop/s) at a given pstate. See also @ref plugin_energy. +/** @brief Return the speed of the processor (in flop/s) at a given pstate. See also @ref plugin_host_energy. * * @param host host to test * @param pstate_index pstate to test @@ -515,7 +519,7 @@ double sg_host_get_available_speed(const_sg_host_t host) /** @brief Returns the number of power states for a host. * - * See also @ref plugin_energy. + * See also @ref plugin_host_energy. */ int sg_host_get_nb_pstates(const_sg_host_t host) { @@ -524,7 +528,7 @@ int sg_host_get_nb_pstates(const_sg_host_t host) /** @brief Gets the pstate at which that host currently runs. * - * See also @ref plugin_energy. + * See also @ref plugin_host_energy. */ int sg_host_get_pstate(const_sg_host_t host) { @@ -532,7 +536,7 @@ int sg_host_get_pstate(const_sg_host_t host) } /** @brief Sets the pstate at which that host should run. * - * See also @ref plugin_energy. + * See also @ref plugin_host_energy. */ void sg_host_set_pstate(sg_host_t host, int pstate) { @@ -543,7 +547,7 @@ void sg_host_set_pstate(sg_host_t host, int pstate) * * @brief Start the host if it is off * - * See also #sg_host_is_on() to test the current state of the host and @ref plugin_energy + * See also #sg_host_is_on() to test the current state of the host and @ref plugin_host_energy * for more info on DVFS. */ void sg_host_turn_on(sg_host_t host) @@ -555,7 +559,7 @@ void sg_host_turn_on(sg_host_t host) * * @brief Stop the host if it is on * - * See also #MSG_host_is_on() to test the current state of the host and @ref plugin_energy + * See also #MSG_host_is_on() to test the current state of the host and @ref plugin_host_energy * for more info on DVFS. */ void sg_host_turn_off(sg_host_t host) @@ -566,8 +570,8 @@ void sg_host_turn_off(sg_host_t host) /** @ingroup m_host_management * @brief Determine if a host is up and running. * - * See also #sg_host_turn_on() and #sg_host_turn_off() to switch the host ON and OFF and @ref plugin_energy for more - * info on DVFS. + * See also #sg_host_turn_on() and #sg_host_turn_off() to switch the host ON and OFF and @ref plugin_host_energy for + * more info on DVFS. * * @param host host to test * @return Returns true if the host is up and running, and false if it's currently down