From cab9c86819184c2e08ba49253d0692f41d2e9b73 Mon Sep 17 00:00:00 2001 From: "James P. Howard, II" Date: Thu, 4 Aug 2022 12:38:29 -0400 Subject: [PATCH] Documentation revisions where appropriate --- README.md | 9 ++++++--- docs/license.rst | 2 +- include/kami/kami.h | 5 +++++ include/kami/population.h | 8 ++++++++ include/kami/random.h | 2 +- include/kami/scheduler.h | 4 ++-- include/kami/sequential.h | 4 ++-- include/kami/staged.h | 8 ++++---- 8 files changed, 29 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 987060f..4ea22fc 100644 --- a/README.md +++ b/README.md @@ -40,15 +40,18 @@ conan create . kami/develop ## Direct Dependencies * [CLI11](https://github.com/CLIUtils/CLI11) +* [Google Test](https://github.com/google/googletest) +* [neargye-semver](https://github.com/Neargye/semver) * [spdlog](https://github.com/gabime/spdlog) -CLI11 and spdlog are both used extensively in the examples and unit -tests. Neither is used directly by the Kami library. +CLI11 and spdlog are both used extensively in the examples. +Neither is used directly by the Kami library. ## Contribution guidelines * Use [GitFlow](http://nvie.com/posts/a-successful-git-branching-model/) - +* Use [Google Test](https://github.com/google/googletest) + ## For more information * James P. Howard, II <> diff --git a/docs/license.rst b/docs/license.rst index ea67f52..083d898 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -1,7 +1,7 @@ License ======= -Copyright (c) 2020 The Johns Hopkins University Applied Physics +Copyright (c) 2020-2022 The Johns Hopkins University Applied Physics Laboratory LLC Permission is hereby granted, free of charge, to any person diff --git a/include/kami/kami.h b/include/kami/kami.h index aa03d96..012b0cb 100644 --- a/include/kami/kami.h +++ b/include/kami/kami.h @@ -42,6 +42,11 @@ namespace kami { class Population; class Scheduler; + /** + * @brief Get the current version of Kami + * + * @return a `semver::version` object containing version information + */ inline semver::version get_version() { return version; } } // namespace kami diff --git a/include/kami/population.h b/include/kami/population.h index dc4f3e1..f9a3fde 100644 --- a/include/kami/population.h +++ b/include/kami/population.h @@ -40,6 +40,14 @@ namespace kami { */ class LIBKAMI_EXPORT Population { protected: + /** + * @brief A mapping of `AgentID` to `Agent` pointers + * + * @details This is the mapping of all `AgentID`s to + * pointers to the corresponding `Agent` in this population. + * This is left exposed as protected should any subclass + * wish to manipulate this mapping directly. + */ std::map> _agent_map; public: diff --git a/include/kami/random.h b/include/kami/random.h index 439d7a2..6122a73 100644 --- a/include/kami/random.h +++ b/include/kami/random.h @@ -73,7 +73,7 @@ namespace kami { * @param model a reference copy of the model * @param agent_list list of agents to execute the step * - * @params returns vector of agents successfully stepped + * @returns returns vector of agents successfully stepped */ std::optional>> step(std::shared_ptr model, std::shared_ptr> agent_list) override; diff --git a/include/kami/scheduler.h b/include/kami/scheduler.h index 89337d8..70c14e9 100644 --- a/include/kami/scheduler.h +++ b/include/kami/scheduler.h @@ -59,7 +59,7 @@ namespace kami { * * @param model a reference copy of the model * - * @params returns vector of agents successfully stepped + * @returns returns vector of agents successfully stepped */ virtual std::optional>> step(std::shared_ptr model) = 0; @@ -74,7 +74,7 @@ namespace kami { * @param model a reference copy of the model * @param agent_list list of agents to execute the step * - * @params returns vector of agents successfully stepped + * @returns returns vector of agents successfully stepped */ virtual std::optional>> step(std::shared_ptr model, std::shared_ptr> agent_list) = 0; }; diff --git a/include/kami/sequential.h b/include/kami/sequential.h index e6cddcf..6c93ac1 100644 --- a/include/kami/sequential.h +++ b/include/kami/sequential.h @@ -58,7 +58,7 @@ namespace kami { * * @param model a reference copy of the model * - * @params returns vector of agents successfully stepped + * @returns returns vector of agents successfully stepped */ std::optional>> step(std::shared_ptr model) override; @@ -73,7 +73,7 @@ namespace kami { * @param model a reference copy of the model * @param agent_list list of agents to execute the step * - * @params returns vector of agents successfully stepped + * @returns returns vector of agents successfully stepped */ std::optional>> step(std::shared_ptr model, std::shared_ptr> agent_list) override; }; diff --git a/include/kami/staged.h b/include/kami/staged.h index 9f0c91f..0524b32 100644 --- a/include/kami/staged.h +++ b/include/kami/staged.h @@ -40,7 +40,7 @@ namespace kami { /** * @brief Will execute all agent steps in a sequential order. * - * @detais A sequential scheduler will iterate over the agents assigned to the scheduler + * @details A sequential scheduler will iterate over the agents assigned to the scheduler * and call their `step()` function in a sequential order. That order is * preserved between calls to `step()` but may be modified by `add_agent()` or * `delete_agent()`. @@ -57,7 +57,7 @@ namespace kami { * * @param model a reference copy of the model * - * @params returns vector of agents successfully advanced + * @returns returns vector of agents successfully advanced */ std::optional>> advance(std::shared_ptr model); @@ -72,7 +72,7 @@ namespace kami { * @param model a reference copy of the model * @param agent_list list of agents to execute the step * - * @params returns vector of agents successfully advanced + * @returns returns vector of agents successfully advanced */ std::optional>> advance(std::shared_ptr model, std::shared_ptr> agent_list); @@ -88,7 +88,7 @@ namespace kami { * @param model a reference copy of the model * @param agent_list list of agents to execute the step * - * @params returns vector of agents successfully stepped + * @returns returns vector of agents successfully stepped */ std::optional>> step(std::shared_ptr model, std::shared_ptr> agent_list) override; };