Doxygenate the code! #3

eyalroz · 2016-11-12T10:43:58Z

Almost all of the code is missing doxygen comments, first and foremost being the methods and the classes. Let's write it.

I changed my mind about `stream_t` construction access, so it is now very similar to `event_t` - owning by default. Additional related changes: * Devices now only create streams wrapped in `stream_t`'s (and those never assume the device is current - for safety reasons, even though we're sacrificing the usage scenario `cuda::device:current::get().create_stream();` * The `cuda::stream` namespace now has `make()` methods which create a stream and a `wrap()` method which wraps an existing stream stream with a `stream_t` (either with or without taking ownership of it) * No more `create()` methods in `cuda::stream` returning `cuda::stream::id_t` (but we do have something lieft in `cuda::stream::detail` * Renamed a data member of `stream_t` `is_owning` -> `owning` * Added: A getter for the `owning` member of `stream_t` * Only one method in `stream_t` for launching kernels: `enqueue_launch` and that's that * Fixed: In `stream_t::enqueue_memory_attachment`, was trying to pass the id_ instead of the device_id_ * Renamed: `stream_t::wait()` ->`stream_t::wait_on()` * Implemented copy and move constructors for `stream_t` to make sure ownership is handled properly, similarly to `event_t` * Now using a (protected) helper method for destruction, `stream_t::destruct()`, both in the destructor and in commented-out assignment and move-assignment operators (I was considering allowing for assignment but got cold feet) * Added: equality and inequality operators for `stream_t`'s, based on the combination of device ID and stream ID Additional unrelated changes: * Added alias types for `cudaIpcMemHandle_t` and `cudaIpcMemHandle_t` (`cuda::memory::ipc::handle_t` and `cuda::event::ipc::handle_t` respectively) * Added an `enqueue_copy()` method to `stream_t` which calls `cuda::memory::async::copy()` - that should have happened a while ago! * Renamed launch to enqueue_launch whenever a possibly non-default stream is concerned - it fits the semantics better, and now we have enqueue_copy as well * the simpleStreams example program no longer printing the binary's name * Using a vector of `stream_t`'s instead of a vector of `stream::id_t`'s in simpleStreams; this means we currently have a lot of .id() calls... I wonder if we shouldn't just have an operator stream::id_t() and be done with it? Hmm * Comment text changes * Added some doxygen here and there * Corrected an exception description string for `cuda::memory::async::copy`

* Added: Doxygen file-level comments for all header files

A generated Doxygen configuration file, which, unfortunately, doesn't help me generate anything significant yet.

* `doxygen.cfg` finally fixed, so that doxygen'ing actually generates anything, yippee!

* Added: A "docs" Make target, so that `make docs` builds the documentation (if `doxygen` is available on your system) * Fixed all doxygen-reported documentation errors * Added documentation to several classes - but of course a huge number still remain entirely undocumented

eyalroz · 2017-09-08T11:37:53Z

Commit 011488e does some doxygenation (forgot to put that in the message.)

* Now using GitHub site main page (`README.md`) as the Doxygen documentation main page as well.

Work on the `device_t` class and related code: * Renamed: `keep_local_mem_allocation_after_launch()` -> `keep_larger_local_mem_after_resize()` (I think this better captures the meaning) * Restricted access to the device_t constructor, so you can now either `device::get(some_id)` or `device::current::get()` - and can't construct devices otherwise * Added: More intelligible aliases for CUDA device attributes (and some type-shuffling to go with that) * Moved some peer-to-peer functionality out of the device_t class (with in-class methods calling out-of-class functions as relevant) * Renamed: `device_t::scoped_setter` -> `device_t::scoped_setter_t` * Doxygenated many types and functions * Spacing tweaks

* Doxygen template tweak re enum value display * Replaced: Occurrences of `{@code foo}` with `\`foo\`` (the former was inappropriately used in several places) * Added: Doxygenation in various files * Fixed: Several doxygen comments were placed after, rather than before, an `enum` item * Spacing tweaks

* Doxygenated: Some functions in `versions.hpp`

* Added: Freestanding function for mapped region pair allocation * `device_t` now calls code in `memory.hpp` for mapped region pair allocation * `device_t` has dropped the templating for mapped region pair allocation; will soon drop templating on everything else - it doesn't do anything, really * More doxygenation, including `///@cond` to hide things from doxygen when necessary * Spacing fixes * Removed: Gratuituous line in `event_t::~event_t` * Corrected (I hope) doxygen comments describing pinning

* More doxygenation * Corrected a few comments * Tweaked some error messages

* Added a method to the `pointer::attributes_t` interface. * Doxygenated `pointer.hpp`

* Doxygenated some more code * Tweaked existing comments * Spacing tweaks

eyalroz · 2017-11-12T22:05:01Z

At this point, we still need to complete doxygenation for:

stream.hpp
profiling.*
unique_ptr.hpp

... and it looks like that's it.

…to memory copy functions.

@url

* Added doxygen `@param` entries for missing parameters * Unified mismatched `@param` names and argument names * Now using `<a>` tags where relevant (not the unsupported @url tage) * Removed some unused/deprecated configuration options from `doxygen.cfg` * Some other doxygen comment tweaks

@url

* Added doxygen `@param` entries for missing parameters * Unified mismatched `@param` names and argument names * Now using `<a>` tags where relevant (not the unsupported @url tage) * Removed some unused/deprecated configuration options from `doxygen.cfg` * Some other doxygen comment tweaks

* Added new Doxygen comments for some constructs. * Fixed typos and out-of-date parameters in many Doxygen comments. * Fixed all Doxygen warnings except for "no documentation for element" and reference resolution failure.