From ceb4972d3e8343b6538409411304386f8a50220f Mon Sep 17 00:00:00 2001 From: Weibin Zeng Date: Tue, 20 Feb 2024 11:39:00 +0800 Subject: [PATCH] [Improvement][Doc][CPP] Complement the api reference document of cpp (#364) --- cpp/include/gar/fwd.h | 71 +++++++++++++++++++++++++++++++++++- cpp/include/gar/graph_info.h | 29 ++++++++++++++- docs/cpp/reference/index.rst | 17 +++++++++ 3 files changed, 114 insertions(+), 3 deletions(-) diff --git a/cpp/include/gar/fwd.h b/cpp/include/gar/fwd.h index 0254401fd..0902539ed 100644 --- a/cpp/include/gar/fwd.h +++ b/cpp/include/gar/fwd.h @@ -33,7 +33,7 @@ namespace GAR_NAMESPACE_INTERNAL { class Status; /** - * A class for representing either a usable value, or an error. + * @brief A class for representing either a usable value, or an error. * * A Result object either contains a value of type `T` or a Status object * explaining why such a value is not present. The type `T` must be @@ -93,18 +93,64 @@ using AdjacentListVector = std::vector>; using VertexInfoVector = std::vector>; using EdgeInfoVector = std::vector>; +/** + * @brief Create a PropertyGroup instance + * + * @param properties Property list of the group + * @param file_type File type of property group chunk file + * @param prefix prefix of property group chunk file. The default + * prefix is the concatenation of property names with '_' as separator + * @return property_group shared_ptr to PropertyGroup + */ std::shared_ptr CreatePropertyGroup( const std::vector& properties, FileType file_type, const std::string& prefix = ""); +/** + * @brief Create a AdjacentList instance + * + * @param type Type of adjacent list + * @param file_type File type of adjacent list chunk file + * @param prefix prefix of adjacent list chunk file, If left empty, the default + * prefix will be set to the name of adjacent list type. + * @return adjacent_list shared_ptr to AdjacentList + */ std::shared_ptr CreateAdjacentList( AdjListType type, FileType file_type, const std::string& prefix = ""); +/** + * @brief Create a VertexInfo instance + * + * @param label The label of the vertex + * @param chunk_size The number of vertices in each vertex chunk + * @param property_groups The property group vector of the vertex + * @param prefix The prefix of the vertex info. If left empty, the default + * prefix will be set to the label of the vertex + * @param version The format version of the vertex info + * @return vertex_info shared_ptr to VertexInfo + */ std::shared_ptr CreateVertexInfo( const std::string& label, IdType chunk_size, const PropertyGroupVector& property_groups, const std::string& prefix = "", std::shared_ptr version = nullptr); +/** + * @brief Create an EdgeInfo instance + * + * @param src_label The label of the source vertex. + * @param edge_label The label of the edge + * @param dst_label The label of the destination vertex + * @param chunk_size The number of edges in each edge chunk + * @param src_chunk_size The number of source vertices in each vertex chunk + * @param dst_chunk_size The number of destination vertices in each vertex + * chunk + * @param directed Whether the edge is directed + * @param adjacent_lists The adjacency list vector of the edge + * @param property_groups The property group vector of the edge + * @param prefix The path prefix of the edge info + * @param version The format version of the edge info + * @return edge_info shared_ptr to EdgeInfo + */ std::shared_ptr CreateEdgeInfo( const std::string& src_label, const std::string& edge_label, const std::string& dst_label, IdType chunk_size, IdType src_chunk_size, @@ -113,18 +159,41 @@ std::shared_ptr CreateEdgeInfo( const PropertyGroupVector& property_groups, const std::string& prefix = "", std::shared_ptr version = nullptr); +/** + * @brief Create a GraphInfo instance + * + * @param name The name of the graph + * @param vertex_infos The vertex info vector of the graph + * @param edge_infos The edge info vector of the graph + * @param prefix The absolute path prefix to store chunk files of the graph. + * Defaults to "./" + * @param version The version of the graph info + * @param extra_info The extra metadata of the graph info + * @return graph_info shared_ptr to GraphInfo + */ std::shared_ptr CreateGraphInfo( const std::string& name, const VertexInfoVector& vertex_infos, const EdgeInfoVector& edge_infos, const std::string& prefix, std::shared_ptr version = nullptr, const std::unordered_map& extra_info = {}); +/// @brief Return a boolean DataType instance const std::shared_ptr& boolean(); +/// @brief Return a int32 DataType instance const std::shared_ptr& int32(); +/// @brief Return a int64 DataType instance const std::shared_ptr& int64(); +/// @brief Return a float32 DataType instance const std::shared_ptr& float32(); +/// @brief Return a float64 DataType instance const std::shared_ptr& float64(); +/// @brief Return a string DataType instance const std::shared_ptr& string(); +/** + * @brief Return a list DataType instance + * + * @param value_type value type of the list + */ std::shared_ptr list(const std::shared_ptr& value_type); namespace util { diff --git a/cpp/include/gar/graph_info.h b/cpp/include/gar/graph_info.h index 0948446a7..0ec2e1ab3 100644 --- a/cpp/include/gar/graph_info.h +++ b/cpp/include/gar/graph_info.h @@ -64,7 +64,7 @@ class PropertyGroup { * Initialize the PropertyGroup with a list of properties, file type, and * optional prefix. * - * @param properties Property list of group + * @param properties Property list of the group * @param file_type File type of property group chunk file * @param prefix prefix of property group chunk file. The default * prefix is the concatenation of property names with '_' as separator @@ -126,19 +126,44 @@ static bool operator==(const PropertyGroup& lhs, const PropertyGroup& rhs) { */ class AdjacentList { public: - /* + /** * Initialize the AdjacentList with the given type, file type, and optional * prefix + * + * @param type Type of adjacent list + * @param file_type File type of adjacent list chunk file + * @param prefix The prefix of the adjacent list. If left empty, the default + * prefix will be set the type name of adjacent list */ explicit AdjacentList(AdjListType type, FileType file_type, const std::string& prefix = ""); + /** + * @brief Get the type of adjacent list + * + * @return The type of adjacent list + */ inline AdjListType GetType() const { return type_; } + /** + * @brief Get the file type of adjacent list + * + * @return The file type of adjacent list + */ inline FileType GetFileType() const { return file_type_; } + /** + * @brief Get the prefix of adjacent list + * + * @return The path prefix of adjacent list + */ inline const std::string& GetPrefix() const { return prefix_; } + /** + * Returns whether the adjacent list is validated. + * + * @return True if the adjacent list is valid, False otherwise. + */ bool IsValidated() const; private: diff --git a/docs/cpp/reference/index.rst b/docs/cpp/reference/index.rst index 297e2317a..d6794375f 100644 --- a/docs/cpp/reference/index.rst +++ b/docs/cpp/reference/index.rst @@ -16,22 +16,31 @@ Graph Info :members: :undoc-members: +.. doxygenfunction:: GraphArchive::CreatePropertyGroup + .. doxygenclass:: GraphArchive::AdjacentList :members: :undoc-members: +.. doxygenfunction:: GraphArchive::CreateAdjacentList + .. doxygenclass:: GraphArchive::VertexInfo :members: :undoc-members: +.. doxygenfunction:: GraphArchive::CreateVertexInfo + .. doxygenclass:: GraphArchive::EdgeInfo :members: :undoc-members: +.. doxygenfunction:: GraphArchive::CreateEdgeInfo + .. doxygenclass:: GraphArchive::GraphInfo :members: :undoc-members: +.. doxygenfunction:: GraphArchive::CreateGraphInfo Readers --------------------- @@ -161,6 +170,14 @@ Data Type :members: :undoc-members: +.. doxygenfunction:: GraphArchive::boolean +.. doxygenfunction:: GraphArchive::int32 +.. doxygenfunction:: GraphArchive::int64 +.. doxygenfunction:: GraphArchive::float32 +.. doxygenfunction:: GraphArchive::float64 +.. doxygenfunction:: GraphArchive::string +.. doxygenfunction:: GraphArchive::list + File Type ~~~~~~~~~~~~~~~~~~~ .. doxygenenum:: GraphArchive::FileType