From 303a053373546c72cf2a27974f54d84c3ce32547 Mon Sep 17 00:00:00 2001 From: Don Acosta <97529984+acostadon@users.noreply.github.com> Date: Wed, 15 Jan 2025 14:27:47 -0500 Subject: [PATCH] added doxygen instrumentation to various cpp include files to use in doxygen (#4864) Adding doxygen groups in cpp to show api Authors: - Don Acosta (https://github.com/acostadon) Approvers: - Brad Rees (https://github.com/BradReesWork) - Chuck Hastings (https://github.com/ChuckHastings) - Seunghwa Kang (https://github.com/seunghwak) URL: https://github.com/rapidsai/cugraph/pull/4864 --- cpp/include/cugraph/algorithms.hpp | 7 ++-- .../cugraph/detail/collect_comm_wrapper.hpp | 12 ++++++- .../cugraph/detail/shuffle_wrappers.hpp | 13 ++++++- cpp/include/cugraph/graph_functions.hpp | 35 ++++++++++++++++++- cpp/include/cugraph/graph_generators.hpp | 13 ++++++- cpp/include/cugraph/legacy/functions.hpp | 13 ++++++- cpp/include/cugraph/legacy/graph.hpp | 13 ++++++- cpp/include/cugraph/sampling_functions.hpp | 34 +++++++++++++----- 8 files changed, 121 insertions(+), 19 deletions(-) diff --git a/cpp/include/cugraph/algorithms.hpp b/cpp/include/cugraph/algorithms.hpp index 5a0a835c617..a2afb161ebc 100644 --- a/cpp/include/cugraph/algorithms.hpp +++ b/cpp/include/cugraph/algorithms.hpp @@ -51,9 +51,6 @@ /** @defgroup traversal_cpp C++ traversal algorithms */ -/** @defgroup labeling_cpp C++ labeling algorithms - */ - /** @defgroup linear_cpp C++ linear assignment algorithms */ @@ -63,7 +60,7 @@ /** @defgroup layout_cpp C++ layout algorithms */ -/** @defgroup component_cpp C++ component algorithms +/** @defgroup components_cpp C++ component algorithms */ /** @defgroup tree_cpp C++ tree algorithms @@ -127,7 +124,7 @@ void jaccard_list(legacy::GraphCSRView const& graph, WT* result); /** -.* @ingroup similarity_cpp + * @ingroup similarity_cpp * @brief Compute overlap coefficient for all vertices in the graph * * Computes the Overlap Coefficient for every pair of vertices in the graph which are diff --git a/cpp/include/cugraph/detail/collect_comm_wrapper.hpp b/cpp/include/cugraph/detail/collect_comm_wrapper.hpp index e547bdb3552..f2307705ac0 100644 --- a/cpp/include/cugraph/detail/collect_comm_wrapper.hpp +++ b/cpp/include/cugraph/detail/collect_comm_wrapper.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2023-2024, NVIDIA CORPORATION. + * Copyright (c) 2023-2025, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -25,6 +25,13 @@ namespace cugraph { namespace detail { +/** @defgroup collect_comm_wrapper_cpp C++ Shuffle Wrappers + */ + +/** @ingroup collect_comm_wrapper_cpp + * @{ + */ + /** * @brief Gather the span of data from all ranks and broadcast the combined data to all ranks. * @@ -42,3 +49,6 @@ rmm::device_uvector device_allgatherv(raft::handle_t const& handle, } // namespace detail } // namespace cugraph +/** + * @} + */ diff --git a/cpp/include/cugraph/detail/shuffle_wrappers.hpp b/cpp/include/cugraph/detail/shuffle_wrappers.hpp index 7dffcce298a..e0d8e7f0275 100644 --- a/cpp/include/cugraph/detail/shuffle_wrappers.hpp +++ b/cpp/include/cugraph/detail/shuffle_wrappers.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2021-2024, NVIDIA CORPORATION. + * Copyright (c) 2021-2025, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -25,6 +25,13 @@ namespace cugraph { namespace detail { +/** @defgroup shuffle_wrappers_cpp C++ Shuffle Wrappers + */ + +/** @ingroup shuffle_wrappers_cpp + * @{ + */ + /** * @brief Shuffle external (i.e. before renumbering) vertex pairs (which can be edge end points) to * their local GPUs based on edge partitioning. @@ -276,3 +283,7 @@ rmm::device_uvector collect_local_vertex_values_from_ext_vertex_value_p } // namespace detail } // namespace cugraph + +/** + * @} + */ diff --git a/cpp/include/cugraph/graph_functions.hpp b/cpp/include/cugraph/graph_functions.hpp index 6a03b9a6454..e85959e164a 100644 --- a/cpp/include/cugraph/graph_functions.hpp +++ b/cpp/include/cugraph/graph_functions.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020-2024, NVIDIA CORPORATION. + * Copyright (c) 2020-2025, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -30,6 +30,9 @@ #include #include +/** @defgroup graph_functions_cpp C++ Graph Funtions + */ + namespace cugraph { template @@ -51,6 +54,7 @@ struct renumber_meta_t }; /** + * @ingroup graph_functions_cpp * @brief renumber edgelist (multi-GPU) * * This function assumes that vertices are pre-shuffled to their target processes and edges are @@ -113,6 +117,7 @@ renumber_edgelist( bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief renumber edgelist (single-GPU) * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -151,6 +156,7 @@ renumber_edgelist(raft::handle_t const& handle, bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Renumber external vertices to internal vertices based on the provided @p * renumber_map_labels. * @@ -182,6 +188,7 @@ void renumber_ext_vertices(raft::handle_t const& handle, bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Unrenumber local internal vertices to external vertices based on the providied @p * renumber_map_labels. * @@ -213,6 +220,7 @@ void unrenumber_local_int_vertices( bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Unrenumber (possibly non-local) internal vertices to external vertices based on the * providied @p renumber_map_labels. * @@ -241,6 +249,7 @@ void unrenumber_int_vertices(raft::handle_t const& handle, bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Unrenumber local edges' internal source & destination IDs to external IDs based on the * provided @p renumber_map_labels (multi-GPU). * @@ -281,6 +290,7 @@ std::enable_if_t unrenumber_local_int_edges( bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Unrenumber local edges' internal source & destination IDs to external IDs based on the * provided @p renumber_map_labels (single-GPU). * @@ -311,6 +321,7 @@ std::enable_if_t unrenumber_local_int_edges(raft::handle_t con bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Renumber local external vertices to internal vertices based on the provided @p * renumber_map_labels. * @@ -341,6 +352,7 @@ void renumber_local_ext_vertices(raft::handle_t const& handle, vertex_t local_int_vertex_last, bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Construct the edge list from the graph view object. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -385,6 +397,7 @@ decompress_to_edgelist( bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Symmetrize edgelist. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -417,6 +430,7 @@ symmetrize_edgelist(raft::handle_t const& handle, bool reciprocal); /** + * @ingroup graph_functions_cpp * @brief Symmetrize the input graph. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -459,6 +473,7 @@ symmetrize_graph( bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Transpose the input graph. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -498,6 +513,7 @@ transpose_graph( bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Transpose the storage format (no change in an actual graph topology). * * In SG, convert between CSR and CSC. In multi-GPU, currently convert between CSR + DCSR hybrid @@ -541,6 +557,7 @@ transpose_graph_storage( bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Compute the coarsened graph. * * Aggregates the vertices with the same label to a new vertex in the output coarsened graph. @@ -588,6 +605,7 @@ coarsen_graph(raft::handle_t const& handle, bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Relabel old labels to new labels. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -621,6 +639,7 @@ void relabel(raft::handle_t const& handle, // FIXME: the first two elements of the returned tuple should be source & destination instead of // major & minor. Major & minor shouldn't be used in the non-detail public API. /** + * @ingroup graph_functions_cpp * @brief extract induced subgraph(s). * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -670,6 +689,7 @@ extract_induced_subgraphs( // implementation) to support different types (arithmetic types or thrust tuple of arithmetic types) // of edge properties. /** + * @ingroup graph_functions_cpp * @brief create a graph from (the optional vertex list and) the given edge list (with optional edge * IDs and types). * @@ -733,6 +753,7 @@ create_graph_from_edgelist(raft::handle_t const& handle, bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief create a graph from (the optional vertex list and) the given edge list (with optional edge * IDs and types). * @@ -799,6 +820,7 @@ create_graph_from_edgelist( bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Find all 2-hop neighbors in the graph * * Find pairs of vertices in the input graph such that each pair is connected by @@ -825,6 +847,7 @@ std::tuple, rmm::device_uvector> get_two std::optional> start_vertices); /** + * @ingroup graph_functions_cpp * @brief Compute per-vertex incoming edge weight sums. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -852,6 +875,7 @@ rmm::device_uvector compute_in_weight_sums( edge_property_view_t edge_weight_view); /** + * @ingroup graph_functions_cpp * @brief Compute per-vertex outgoing edge weight sums. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -879,6 +903,7 @@ rmm::device_uvector compute_out_weight_sums( edge_property_view_t edge_weight_view); /** + * @ingroup graph_functions_cpp * @brief Compute maximum per-vertex incoming edge weight sums. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -906,6 +931,7 @@ weight_t compute_max_in_weight_sum( edge_property_view_t edge_weight_view); /** + * @ingroup graph_functions_cpp * @brief Compute maximum per-vertex outgoing edge weight sums. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -933,6 +959,7 @@ weight_t compute_max_out_weight_sum( edge_property_view_t edge_weight_view); /** + * @ingroup graph_functions_cpp * @brief Sum the weights of the entire set of edges. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -959,6 +986,7 @@ weight_t compute_total_edge_weight( edge_property_view_t edge_weight_view); /** + * @ingroup graph_functions_cpp * @brief Select random vertices * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -991,6 +1019,7 @@ rmm::device_uvector select_random_vertices( bool do_expensive_check = false); /** + * @ingroup graph_functions_cpp * @brief Remove self loops from an edge list * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -1022,6 +1051,7 @@ remove_self_loops(raft::handle_t const& handle, std::optional>&& edgelist_edge_types); /** + * @ingroup graph_functions_cpp * @brief Remove all but one edge when a multi-edge exists. * * When a multi-edge exists, one of the edges will remain. If @p keep_min_value_edge is false, an @@ -1069,6 +1099,7 @@ remove_multi_edges(raft::handle_t const& handle, bool keep_min_value_edge = false); /** + * @ingroup graph_functions_cpp * @brief Shuffle external vertex ids to the proper GPU. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -1083,6 +1114,7 @@ rmm::device_uvector shuffle_external_vertices(raft::handle_t const& ha rmm::device_uvector&& vertices); /** + * @ingroup graph_functions_cpp * @brief Shuffle external vertex ids and values to the proper GPU. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -1102,6 +1134,7 @@ shuffle_external_vertex_value_pairs(raft::handle_t const& handle, rmm::device_uvector&& values); /** + * @ingroup graph_functions_cpp * @brief Shuffle external edges to the proper GPU. * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. diff --git a/cpp/include/cugraph/graph_generators.hpp b/cpp/include/cugraph/graph_generators.hpp index 5e8e97c51a2..7246f0b2fb7 100644 --- a/cpp/include/cugraph/graph_generators.hpp +++ b/cpp/include/cugraph/graph_generators.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2021-2023, NVIDIA CORPORATION. + * Copyright (c) 2021-2025, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -24,6 +24,13 @@ #include #include +/** @defgroup graph_generators_cpp C++ Graph Generators + */ + +/** @ingroup graph_generators_cpp + * @{ + */ + namespace cugraph { /** @@ -536,3 +543,7 @@ combine_edgelists(raft::handle_t const& handle, bool remove_multi_edges = true); } // namespace cugraph + +/** + * @} + */ diff --git a/cpp/include/cugraph/legacy/functions.hpp b/cpp/include/cugraph/legacy/functions.hpp index 51f05a6d26d..1e4156a68b3 100644 --- a/cpp/include/cugraph/legacy/functions.hpp +++ b/cpp/include/cugraph/legacy/functions.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020-2024, NVIDIA CORPORATION. + * Copyright (c) 2020-2025, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -24,6 +24,13 @@ namespace cugraph { +/** @defgroup legacy_functions_cpp C++ Shuffle Wrappers + */ + +/** @ingroup shuffle_wrappers_cpp + * @{ + */ + /** * @brief Convert COO to CSR * @@ -68,3 +75,7 @@ void comms_bcast(const raft::handle_t& handle, value_t* value, size_t count) } } // namespace cugraph + +/** + * @} + */ diff --git a/cpp/include/cugraph/legacy/graph.hpp b/cpp/include/cugraph/legacy/graph.hpp index 19cd5bbd6d0..18d57533d62 100644 --- a/cpp/include/cugraph/legacy/graph.hpp +++ b/cpp/include/cugraph/legacy/graph.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020-2024, NVIDIA CORPORATION. + * Copyright (c) 2020-2025, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -48,6 +48,13 @@ enum class DegreeDirection { DEGREE_DIRECTION_COUNT }; +/** @defgroup legacy_graph_cpp C++ Legacy Graph + */ + +/** @ingroup legacy_graph_cpp + * @{ + */ + /** * @brief Base class graphs, all but vertices and edges * @@ -575,3 +582,7 @@ struct invalid_edge_id : invalid_idx {}; } // namespace cugraph #include "eidecl_graph.hpp" + +/** + * @} + */ diff --git a/cpp/include/cugraph/sampling_functions.hpp b/cpp/include/cugraph/sampling_functions.hpp index 981c42135f6..35c51c1ea6d 100644 --- a/cpp/include/cugraph/sampling_functions.hpp +++ b/cpp/include/cugraph/sampling_functions.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020-2024, NVIDIA CORPORATION. + * Copyright (c) 2020-2025, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -27,9 +27,13 @@ #include #include +/** @defgroup sampling_functions_cpp C++ Sampling Functions + */ + namespace cugraph { /** + * @ingroup sampling_functions_cpp * @brief Controls how we treat prior sources in sampling * * @param DEFAULT Add vertices encountered while sampling to the new frontier @@ -41,6 +45,7 @@ namespace cugraph { enum class prior_sources_behavior_t { DEFAULT = 0, CARRY_OVER, EXCLUDE }; /** + * @ingroup sampling_functions_cpp * @brief Uniform Neighborhood Sampling. * * @deprecated Replaced with homogeneous_uniform_neighbor_sample @@ -141,6 +146,7 @@ uniform_neighbor_sample( bool do_expensive_check = false); /** + * @ingroup sampling_functions_cpp * @brief Biased Neighborhood Sampling. * * @deprecated Replaced with homogeneous_biased_neighbor_sample @@ -273,6 +279,7 @@ struct sampling_flags_t { }; /** + * @ingroup sampling_functions_cpp * @brief Homogeneous Uniform Neighborhood Sampling. * * This function traverses from a set of starting vertices, traversing outgoing edges and @@ -347,6 +354,7 @@ homogeneous_uniform_neighbor_sample( bool do_expensive_check = false); /** + * @ingroup sampling_functions_cpp * @brief Homogeneous Biased Neighborhood Sampling. * * This function traverses from a set of starting vertices, traversing outgoing edges and @@ -428,6 +436,7 @@ homogeneous_biased_neighbor_sample( bool do_expensive_check = false); /** + * @ingroup sampling_functions_cpp * @brief Heterogeneous Uniform Neighborhood Sampling. * * This function traverses from a set of starting vertices, traversing outgoing edges and @@ -506,6 +515,7 @@ heterogeneous_uniform_neighbor_sample( bool do_expensive_check = false); /** + * @ingroup sampling_functions_cpp * @brief Heterogeneous Biased Neighborhood Sampling. * * This function traverses from a set of starting vertices, traversing outgoing edges and @@ -590,7 +600,8 @@ heterogeneous_biased_neighbor_sample( sampling_flags_t sampling_flags, bool do_expensive_check = false); -/* +/** + * @ingroup sampling_functions_cpp * @brief renumber sampled edge list and compress to the (D)CSR|(D)CSC format. * * This function renumbers sampling function (e.g. uniform_neighbor_sample) output edges fulfilling @@ -715,7 +726,8 @@ renumber_and_compress_sampled_edgelist( bool doubly_compress = false, bool do_expensive_check = false); -/* +/** + * @ingroup sampling_functions_cpp * @brief renumber sampled edge list and sort the renumbered edges. * * This function renumbers sampling function (e.g. uniform_neighbor_sample) output edges fulfilling @@ -815,7 +827,8 @@ renumber_and_sort_sampled_edgelist( bool src_is_major = true, bool do_expensive_check = false); -/* +/** + * @ingroup sampling_functions_cpp * @brief renumber sampled edge list (vertex & edge IDs) per vertex/edge type and sort the * renumbered edges. * @@ -957,7 +970,8 @@ heterogeneous_renumber_and_sort_sampled_edgelist( bool src_is_major = true, bool do_expensive_check = false); -/* +/** + * @ingroup sampling_functions_cpp * @brief sort sampled edge list. * * Sampled edges are sorted based on the following rules. @@ -1024,7 +1038,8 @@ sort_sampled_edgelist(raft::handle_t const& handle, size_t num_hops, bool src_is_major = true, bool do_expensive_check = false); -/* +/** + * @ingroup sampling_functions_cpp * @brief Build map to lookup source and destination using edge id and type * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -1047,7 +1062,8 @@ lookup_container_t build_edge_id_and_type_to_src_ edge_property_view_t edge_id_view, edge_property_view_t edge_type_view); -/* +/** + * @ingroup sampling_functions_cpp * @brief Lookup edge sources and destinations using edge ids and a single edge type. * Use this function to lookup endpoints of edges belonging to the same edge type. * @@ -1074,7 +1090,8 @@ lookup_endpoints_from_edge_ids_and_single_type( raft::device_span edge_ids_to_lookup, edge_type_t edge_type_to_lookup); -/* +/** + * @ingroup sampling_functions_cpp * @brief Lookup edge sources and destinations using edge ids and edge types. * Use this function to lookup endpoints of edges belonging to different edge types. * @@ -1104,6 +1121,7 @@ lookup_endpoints_from_edge_ids_and_types( raft::device_span edge_types_to_lookup); /** + * @ingroup sampling_functions_cpp * @brief Negative Sampling * * This function generates negative samples for graph.