From 09c3c02c33ced3ab097fb6a1443c03d88a7ddcb3 Mon Sep 17 00:00:00 2001 From: q66 Date: Wed, 12 Apr 2017 19:12:09 +0200 Subject: [PATCH] doc cleanups --- doc/Doxyfile | 2 +- ostd/channel.hh | 35 +++++---------------- ostd/concurrency.hh | 32 ++++++++++--------- ostd/coroutine.hh | 69 ++++++++++++++++++----------------------- ostd/generic_condvar.hh | 11 ++----- ostd/io.hh | 2 -- ostd/platform.hh | 10 ++++-- ostd/range.hh | 9 ------ ostd/stream.hh | 2 -- ostd/thread_pool.hh | 2 +- 10 files changed, 67 insertions(+), 107 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index d880a8f..70c835b 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -435,7 +435,7 @@ LOOKUP_CACHE_SIZE = 0 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = YES +EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. diff --git a/ostd/channel.hh b/ostd/channel.hh index 18999f3..03507f8 100644 --- a/ostd/channel.hh +++ b/ostd/channel.hh @@ -32,7 +32,7 @@ namespace ostd { * @{ */ -/** Thrown when manipulating a channel that has been closed. */ +/** @brief Thrown when manipulating a channel that has been closed. */ struct channel_error: std::logic_error { using std::logic_error::logic_error; }; @@ -48,6 +48,12 @@ struct channel_error: std::logic_error { * state is freed as soon as the last channel instance referencing it is * destroyed. * + * Channels are move constructible. Moving a channel transfers the state + * into another channel and leaves the original state in an unusable + * state, with no reference count change. Copying a channel increases + * the reference count, so both instances point to the ssame state and + * both are valid. + * * @tparam T The type of the values in the queue. */ template @@ -80,34 +86,9 @@ struct channel { template channel(F func): p_state(new impl{func}) {} - /** @brief Creates a new reference to the channel. - * - * This does not copy per se, as channels store a refcounted internal - * state. It increments the reference count on the state and creates - * a new channel instance that references this state. - * - * If you don't want to increment and instead you want to transfer the - * reference to a new instance, use channel(channel &&). - * - * @see channel(channel &&), operator=(channel const &) - */ channel(channel const &) = default; - - /** @brief Moves the internal state reference to a new channel instance. - * - * This is like channel(channel const &) except it does not increment - * the reference; it moves the reference to a new container instead, - * leaving the other one uninitialized. You cannot use the channel - * the reference was moved from anymore afterwards. - * - * @see channel(channel const &), operator=(channel &&) - */ channel(channel &&) = default; - - /** @see channel(channel const &) */ channel &operator=(channel const &) = default; - - /** @see channel(channel &&) */ channel &operator=(channel &&) = default; /** @brief Inserts a copy of a value into the queue. @@ -205,7 +186,7 @@ struct channel { return p_state->closed(); } - /** Closes the channel. No effect if already closed. */ + /** @brief Closes the channel. No effect if already closed. */ void close() noexcept { p_state->close(); } diff --git a/ostd/concurrency.hh b/ostd/concurrency.hh index 418861a..c247028 100644 --- a/ostd/concurrency.hh +++ b/ostd/concurrency.hh @@ -97,23 +97,16 @@ private: }; protected: - /** Does nothing, this base class is empty. */ + /** @brief Does nothing, this base class is empty. */ scheduler() {} public: - /** Does nothing, this base class is empty. */ + /** @brief Does nothing, this base class is empty. */ virtual ~scheduler() {} - /** A scheduler is not copy constructible. */ scheduler(scheduler const &) = delete; - - /** A scheduler is not move constructible. */ scheduler(scheduler &&) = delete; - - /** A scheduler is not copy assignable. */ scheduler &operator=(scheduler const &) = delete; - - /** A scheduler is not move assignable. */ scheduler &operator=(scheduler &&) = delete; /** @brief Spawns a task. @@ -128,7 +121,7 @@ public: /** @brief Tells the scheduler to re-schedule the current task. * - * In #ostd::thread_scheduler, this is just a hint, as it uses OS threading + * In ostd::thread_scheduler, this is just a hint, as it uses OS threading * facilities. In coroutine based schedulers, this will typically suspend * the currently running task and re-schedule it for later. * @@ -136,7 +129,7 @@ public: */ virtual void yield() noexcept = 0; - /** @brief Creates a condition variable using #ostd::generic_condvar. + /** @brief Creates a condition variable using ostd::generic_condvar. * * A scheduler might be using a custom condition variable type depending * on how its tasks are implemented. Other data structures might want to @@ -292,7 +285,10 @@ namespace detail { */ template struct basic_thread_scheduler: scheduler { - /* @brief Creates the scheduler. + /** @brief The stack allocator type. */ + using allocator_type = SA; + + /** @brief Creates the scheduler. * * @param[in] sa The provided stack allocator. */ @@ -393,7 +389,7 @@ private: std::mutex p_lock; }; -/** An #ostd::basic_thread_scheduler using #ostd::stack_pool. */ +/** @brief An ostd::basic_thread_scheduler using ostd::stack_pool. */ using thread_scheduler = basic_thread_scheduler; namespace detail { @@ -464,6 +460,9 @@ namespace detail { */ template struct basic_simple_coroutine_scheduler: scheduler { + /** @brief The stack allocator type. */ + using allocator_type = SA; + private: /* simple one just for channels */ struct coro_cond { @@ -620,7 +619,7 @@ private: typename std::list::iterator p_idx = p_coros.end(); }; -/** An #ostd::basic_simple_coroutine_scheduler using #ostd::stack_pool. */ +/** @brief An ostd::basic_simple_coroutine_scheduler using ostd::stack_pool. */ using simple_coroutine_scheduler = basic_simple_coroutine_scheduler; /** @brief A scheduler that uses a coroutine type for tasks on several threads. @@ -636,6 +635,9 @@ using simple_coroutine_scheduler = basic_simple_coroutine_scheduler; */ template struct basic_coroutine_scheduler: scheduler { + /** @brief The stack allocator type. */ + using allocator_type = SA; + private: struct task_cond; struct task; @@ -961,7 +963,7 @@ private: tlist p_running; }; -/** An #ostd::basic_coroutine_scheduler using #ostd::stack_pool. */ +/** @brief An ostd::basic_coroutine_scheduler using ostd::stack_pool. */ using coroutine_scheduler = basic_coroutine_scheduler; /** @brief Spawns a task on the currently in use scheduler. diff --git a/ostd/coroutine.hh b/ostd/coroutine.hh index 5c5a896..cac4ad7 100644 --- a/ostd/coroutine.hh +++ b/ostd/coroutine.hh @@ -99,7 +99,7 @@ struct coroutine_context { } protected: - /** Does nothing, just default-initializes the members. */ + /** @brief Does nothing, just default-initializes the members. */ coroutine_context() {} /** @brief Unwinds the stack and frees it. @@ -115,7 +115,6 @@ protected: free_stack(); } - /** Coroutine contexts are not copy constructible. */ coroutine_context(coroutine_context const &) = delete; /** @brief Moves the given context into this one. @@ -134,7 +133,6 @@ protected: c.set_dead(); } - /** Coroutine contexts are not copy assignable. */ coroutine_context &operator=(coroutine_context const &) = delete; /** @brief Moves the given context into this one. @@ -203,22 +201,22 @@ protected: p_orig = detail::ostd_jump_fcontext(p_orig, nullptr).ctx; } - /** Checks if the coroutine is suspended. */ + /** @brief Checks if the coroutine is suspended. */ bool is_hold() const { return (p_state == state::HOLD); } - /** Checks if the coroutine is dead. */ + /** @brief Checks if the coroutine is dead. */ bool is_dead() const { return (p_state == state::TERM); } - /** Marks the coroutine as dead. Only valid without an active context. */ + /** @brief Marks the coroutine as dead. Only valid without an active context. */ void set_dead() { p_state = state::TERM; } - /** Marks the coroutine as executing. Only valid before coro_jump(). */ + /** @brief Marks the coroutine as executing. Only valid before coro_jump(). */ void set_exec() { p_state = state::EXEC; } @@ -235,7 +233,7 @@ protected: } } - /** Swaps the current context with another. */ + /** @brief Swaps the current context with another. */ void swap(coroutine_context &other) noexcept { using std::swap; swap(p_stack, other.p_stack); @@ -725,10 +723,9 @@ private: }; public: - /** The yielder type for the coroutine. Not opaque, but internal. */ + /** @brief The yielder type for the coroutine. Not opaque, but internal. */ using yield_type = yielder; - /** Coroutines are not default constructible. */ coroutine() = delete; /** @brief Creates a coroutine using the given function. @@ -763,7 +760,6 @@ public: this->set_dead(); } - /** Coroutines are not copy constructible. */ coroutine(coroutine const &) = delete; /** @brief Moves a coroutine. @@ -779,7 +775,6 @@ public: c.p_stor.p_func = nullptr; } - /** Coroutines are not copy assignable. */ coroutine &operator=(coroutine const &) = delete; /** @brief Moves a coroutine. @@ -791,7 +786,7 @@ public: p_stor.swap(c.p_stor); } - /** Checks if the coroutine is alive, returning `true` if it is. */ + /** @brief Checks if the coroutine is alive. */ explicit operator bool() const noexcept { return !this->is_dead(); } @@ -833,13 +828,13 @@ public: return p_stor.get_result(); } - /** Swaps two coroutines' states. */ + /** @brief Swaps two coroutines' states. */ void swap(coroutine &other) noexcept { p_stor.swap(other.p_stor); base_t::swap(other); } - /** Returns the RTTI of the function stored in the coroutine. */ + /** @brief Returns the RTTI of the function stored in the coroutine. */ std::type_info const &target_type() const { return p_stor.p_func.target_type(); } @@ -868,7 +863,7 @@ private: detail::coro_stor p_stor; }; -/** Swaps two coroutines' states. */ +/** @brief Swaps two coroutines' states. */ template inline void swap(coroutine &a, coroutine &b) noexcept { a.swap(b); @@ -970,13 +965,12 @@ private: }; public: - /** As generators can be used with ranges, this is defined. */ + /** @brief As generators can be used with ranges, this is defined. */ using range = generator_range; - /** The yielder type for the generator. Not opaque, but internal. */ + /** @brief The yielder type for the generator. Not opaque, but internal. */ using yield_type = yielder; - /** Generators are not default constructible. */ generator() = delete; /** @brief Creates a generator using the given function. @@ -1018,7 +1012,6 @@ public: this->set_dead(); } - /** Generators are not copy constructible. */ generator(generator const &) = delete; /** @brief Moves a generator. @@ -1035,7 +1028,6 @@ public: c.p_result = nullptr; } - /** Generators are not copy assignable. */ generator &operator=(generator const &) = delete; /** @brief Moves a generator. @@ -1050,7 +1042,7 @@ public: c.p_result = nullptr; } - /** Checks if the generator is alive, returning `true` if it is. */ + /** @brief Checks if the generator is alive. */ explicit operator bool() const noexcept { return !this->is_dead(); } @@ -1100,7 +1092,7 @@ public: return *p_result; } - /** Checks if the generator is has a value, returning `false` if it does. */ + /** @brief Checks if the generator has no value. */ bool empty() const noexcept { return !p_result; } @@ -1113,19 +1105,19 @@ public: */ generator_range iter() noexcept; - /** Implements a minimal iterator just for range-based for loop. - * Do not use directly. + /** @brief Implements a minimal iterator just for range-based for loop. + * Do not use directly. */ detail::generator_iterator begin() noexcept; - /** Implements a minimal iterator just for range-based for loop. - * Do not use directly. + /** @brief Implements a minimal iterator just for range-based for loop. + * Do not use directly. */ std::nullptr_t end() noexcept { return nullptr; } - /** Swaps two generators' states. */ + /** @brief Swaps two generators' states. */ void swap(generator &other) noexcept { using std::swap; swap(p_func, other.p_func); @@ -1133,7 +1125,7 @@ public: coroutine_context::swap(other); } - /** Returns the RTTI of the function stored in the generator. */ + /** @brief Returns the RTTI of the function stored in the generator. */ std::type_info const &target_type() const { return p_func.target_type(); } @@ -1168,7 +1160,7 @@ private: std::remove_reference_t *p_result = nullptr; }; -/** Swaps two generators' states. */ +/** @brief Swaps two generators' states. */ template inline void swap(generator &a, generator &b) noexcept { a.swap(b); @@ -1207,34 +1199,33 @@ struct generator_range: input_range> { using size_type = std::size_t; using difference_type = std::ptrdiff_t; - /** Generator ranges are not default constructible. */ generator_range() = delete; - /** Generator ranges are constructed using a reference to a generator. */ + /** @brief Generator ranges are constructed using a generator reference. */ generator_range(generator &g): p_gen(&g) {} - /** Like ostd::generator::empty(). */ + /** @brief Like ostd::generator::empty(). */ bool empty() const noexcept { return p_gen->empty(); } - /** Like ostd::generator::resume(). */ + /** @brief Like ostd::generator::resume(). */ void pop_front() { p_gen->resume(); } - /** Like ostd::generator::value(). */ + /** @brief Like ostd::generator::value(). */ reference front() const { return p_gen->value(); } - /** Implements a minimal iterator just for range-based for loop. - * Do not use directly. + /** @brief Implements a minimal iterator just for range-based for loop. + * Do not use directly. */ detail::generator_iterator begin() noexcept; - /** Implements a minimal iterator just for range-based for loop. - * Do not use directly. + /** @brief Implements a minimal iterator just for range-based for loop. + * Do not use directly. */ std::nullptr_t end() noexcept { return nullptr; diff --git a/ostd/generic_condvar.hh b/ostd/generic_condvar.hh index 5de40de..48ac09e 100644 --- a/ostd/generic_condvar.hh +++ b/ostd/generic_condvar.hh @@ -65,7 +65,7 @@ namespace detail { * space is the size of that). */ struct generic_condvar { - /** Constructs the condvar using std::condition_variable. */ + /** @brief Constructs the condvar using std::condition_variable. */ generic_condvar() { new (reinterpret_cast(&p_condbuf)) detail::cond_impl(); @@ -86,19 +86,12 @@ struct generic_condvar { detail::cond_impl>(func); } - /** Condvars are not copy constructible. */ generic_condvar(generic_condvar const &) = delete; - - /** Condvars are not move constructible. */ generic_condvar(generic_condvar &&) = delete; - - /** Condvars are not copy assignable. */ generic_condvar &operator=(generic_condvar const &) = delete; - - /** Condvars are not move assignable. */ generic_condvar &operator=(generic_condvar &&) = delete; - /** Destroys the stored condvar. */ + /** @brief Destroys the stored condvar. */ ~generic_condvar() { reinterpret_cast(&p_condbuf)->~cond_iface(); } diff --git a/ostd/io.hh b/ostd/io.hh index 068da1a..bede6f3 100644 --- a/ostd/io.hh +++ b/ostd/io.hh @@ -66,7 +66,6 @@ struct OSTD_EXPORT file_stream: stream { */ file_stream(): p_f(), p_owned(false) {} - /** @brief File streams are not copy constructible. */ file_stream(file_stream const &) = delete; /** @brief Creates a file stream by moving. @@ -107,7 +106,6 @@ struct OSTD_EXPORT file_stream: stream { /** @brief Calls close() on the stream. */ ~file_stream() { close(); } - /** @brief File streams are not copy assignable. */ file_stream &operator=(file_stream const &) = delete; /** @brief Assigns another stream to this one by move. diff --git a/ostd/platform.hh b/ostd/platform.hh index 2b1e463..95b7317 100644 --- a/ostd/platform.hh +++ b/ostd/platform.hh @@ -231,7 +231,7 @@ namespace ostd { * @{ */ -#if defined(OSTD_TOOLCHAIN_GNU) +#if defined(OSTD_TOOLCHAIN_GNU) && !defined(OSTD_GENERATING_DOC) /* using gcc/clang builtins */ inline std::uint16_t endian_swap16(std::uint16_t x) noexcept { @@ -244,7 +244,7 @@ inline std::uint64_t endian_swap64(std::uint64_t x) noexcept { return __builtin_bswap64(x); } -#elif defined(OSTD_TOOLCHAIN_MSVC) +#elif defined(OSTD_TOOLCHAIN_MSVC) && !defined(OSTD_GENERATING_DOC) /* using msvc builtins */ inline std::uint16_t endian_swap16(std::uint16_t x) noexcept { @@ -261,12 +261,18 @@ inline std::uint64_t endian_swap64(std::uint64_t x) noexcept { #else /* fallback */ + +/** @brief 16-bit byte swap. */ inline std::uint16_t endian_swap16(std::uint16_t x) noexcept { return (x << 8) | (x >> 8); } + +/** @brief 32-bit byte swap. */ inline std::uint32_t endian_swap32(std::uint32_t x) noexcept { return (x << 24) | (x >> 24) | ((x >> 8) & 0xFF00) | ((x << 8) & 0xFF0000); } + +/** @brief 64-bit byte swap. */ inline std::uint64_t endian_swap64(std::uint64_t x) noexcept { return endian_swap32( std::uint32_t(x >> 32)) | diff --git a/ostd/range.hh b/ostd/range.hh index 11c3c16..d15dfd5 100644 --- a/ostd/range.hh +++ b/ostd/range.hh @@ -782,7 +782,6 @@ private: size_type p_written = 0; public: - /** @brief A range to wrap is needed. */ counting_output_range() = delete; /** @brief Constructs the range from an existing range. */ @@ -1017,7 +1016,6 @@ private: T p_range; public: - /** @brief Not default constructible. */ reverse_range() = delete; /** @brief Constructs a reverse range from a range. */ @@ -1099,7 +1097,6 @@ private: T p_range; public: - /** @brief Not default constructible. */ move_range() = delete; /** @brief Constructs a move range from a range. */ @@ -1139,7 +1136,6 @@ struct number_range: input_range> { using size_type = std::size_t; using difference_type = std::ptrdiff_t; - /** @brief Not default constructible. */ number_range() = delete; /** @brief Constructs the range from inputs. @@ -1240,7 +1236,6 @@ private: size_type p_index; public: - /** @brief Not default constructible. */ enumerated_range() = delete; /** @brief Constructs an enumerated range from a range. */ @@ -1296,7 +1291,6 @@ private: size_type p_remaining; public: - /** @brief Not default constructible. */ take_range() = delete; /** @brief Constructs the range with some number of elements. */ @@ -1347,7 +1341,6 @@ private: size_type p_chunksize; public: - /** @brief Not default constructible. */ chunks_range() = delete; /** @brief Constructs the range with some number of elements per chunk. */ @@ -1416,7 +1409,6 @@ private: std::tuple p_ranges; public: - /** @brief Not default constructible. */ join_range() = delete; /** @brief Constructs the range from some ranges. */ @@ -1484,7 +1476,6 @@ private: std::tuple p_ranges; public: - /** @brief Not default constructible. */ zip_range() = delete; /** @brief Constructs the range from some ranges. */ diff --git a/ostd/stream.hh b/ostd/stream.hh index aa4bbbc..643cb29 100644 --- a/ostd/stream.hh +++ b/ostd/stream.hh @@ -560,7 +560,6 @@ struct stream_range: input_range> { using size_type = std::size_t; using difference_type = stream_off_t; - /** @brief Stream ranges are not default constructible. */ stream_range() = delete; /** @brief Creates a stream range using a stream. */ @@ -674,7 +673,6 @@ struct stream_line_range: input_range> { using size_type = std::size_t; using difference_type = stream_off_t; - /** @brief Stream line ranges are not default constructible. */ stream_line_range() = delete; /** @brief Creates a stream line range using a stream. diff --git a/ostd/thread_pool.hh b/ostd/thread_pool.hh index 666bc3d..be5a932 100644 --- a/ostd/thread_pool.hh +++ b/ostd/thread_pool.hh @@ -126,7 +126,7 @@ struct thread_pool { } } - /** Calls destroy(). */ + /** @brief Calls destroy(). */ ~thread_pool() { destroy(); }