Skip to content

GitLab

Unverified Commit bcd37684 authored by Hongzhi (Steve), Chen's avatar Hongzhi (Steve), Chen Committed by GitHub
Browse files

[Misc] Replace /*! with /**. (#4823) 



* replace

* blabla

* balbla

* blabla
Co-authored-by: default avatarSteve <ubuntu@ip-172-31-34-29.ap-northeast-1.compute.internal>
parent 619d735d
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 614 additions and 617 deletions
featgraph/include/featgraph.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file featgraph/include/featgraph.h
* @brief FeatGraph kernel headers.
......
featgraph/src/featgraph.cc
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file featgraph/src/featgraph.cc
* @brief FeatGraph kernels.
......
featgraph/src/tvm_runtime_pack.cc
View file @ bcd37684
/*
/**
* NOTE(zihao): this file was modified from TVM project:
* -
* https://github.com/apache/tvm/blob/9713d675c64ae3075e10be5acadeef1328a44bb5/apps/howto_deploy/tvm_runtime_pack.cc
......@@ -21,7 +21,7 @@
* under the License.
*/
/*!
/**
* @brief This is an all in one TVM runtime file.
*
* You only have to use this file to compile libtvm_runtime to
......
include/dgl/array.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/array.h
* @brief Common array operations required by DGL.
......
include/dgl/array_iterator.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/array_iterator.h
* @brief Various iterators.
......
include/dgl/aten/array_ops.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/aten/array_ops.h
* @brief Common array operations required by DGL.
......@@ -23,20 +23,20 @@ namespace aten {
// ID array
//////////////////////////////////////////////////////////////////////
/*! @return A special array to represent null. */
/** @return A special array to represent null. */
inline NDArray NullArray(const DGLDataType& dtype = DGLDataType{kDGLInt, 64, 1},
const DGLContext& ctx = DGLContext{kDGLCPU, 0}) {
return NDArray::Empty({0}, dtype, ctx);
}
/*!
/**
* @return Whether the input array is a null array.
*/
inline bool IsNullArray(NDArray array) {
return array->shape[0] == 0;
}
/*!
/**
* @brief Create a new id array with given length
* @param length The array length
* @param ctx The array context
......@@ -47,7 +47,7 @@ IdArray NewIdArray(int64_t length,
DGLContext ctx = DGLContext{kDGLCPU, 0},
uint8_t nbits = 64);
/*!
/**
* @brief Create a new id array using the given vector data
* @param vec The vector data
* @param nbits The integer bits of the returned array
......@@ -59,7 +59,7 @@ IdArray VecToIdArray(const std::vector<T>& vec,
uint8_t nbits = 64,
DGLContext ctx = DGLContext{kDGLCPU, 0});
/*!
/**
* @brief Return an array representing a 1D range.
* @param low Lower bound (inclusive).
* @param high Higher bound (exclusive).
......@@ -69,7 +69,7 @@ IdArray VecToIdArray(const std::vector<T>& vec,
*/
IdArray Range(int64_t low, int64_t high, uint8_t nbits, DGLContext ctx);
/*!
/**
* @brief Return an array full of the given value
* @param val The value to fill.
* @param length Number of elements.
......@@ -79,7 +79,7 @@ IdArray Range(int64_t low, int64_t high, uint8_t nbits, DGLContext ctx);
*/
IdArray Full(int64_t val, int64_t length, uint8_t nbits, DGLContext ctx);
/*!
/**
* @brief Return an array full of the given value with the given type.
* @param val The value to fill.
* @param length Number of elements.
......@@ -89,13 +89,13 @@ IdArray Full(int64_t val, int64_t length, uint8_t nbits, DGLContext ctx);
template <typename DType>
NDArray Full(DType val, int64_t length, DGLContext ctx);
/*! @brief Create a deep copy of the given array */
/** @brief Create a deep copy of the given array */
IdArray Clone(IdArray arr);
/*! @brief Convert the idarray to the given bit width */
/** @brief Convert the idarray to the given bit width */
IdArray AsNumBits(IdArray arr, uint8_t bits);
/*! @brief Arithmetic functions */
/** @brief Arithmetic functions */
IdArray Add(IdArray lhs, IdArray rhs);
IdArray Sub(IdArray lhs, IdArray rhs);
IdArray Mul(IdArray lhs, IdArray rhs);
......@@ -138,30 +138,30 @@ IdArray LE(int64_t lhs, IdArray rhs);
IdArray EQ(int64_t lhs, IdArray rhs);
IdArray NE(int64_t lhs, IdArray rhs);
/*! @brief Stack two arrays (of len L) into a 2*L length array */
/** @brief Stack two arrays (of len L) into a 2*L length array */
IdArray HStack(IdArray arr1, IdArray arr2);
/*! @brief Return the indices of the elements that are non-zero. */
/** @brief Return the indices of the elements that are non-zero. */
IdArray NonZero(BoolArray bool_arr);
/*!
/**
* @brief Return the data under the index. In numpy notation, A[I]
* @tparam ValueType The type of return value.
*/
template<typename ValueType>
ValueType IndexSelect(NDArray array, int64_t index);
/*!
/**
* @brief Return the data under the index. In numpy notation, A[I]
*/
NDArray IndexSelect(NDArray array, IdArray index);
/*!
/**
* @brief Return the data from `start` (inclusive) to `end` (exclusive).
*/
NDArray IndexSelect(NDArray array, int64_t start, int64_t end);
/*!
/**
* @brief Permute the elements of an array according to given indices.
*
* Only support 1D arrays.
......@@ -175,7 +175,7 @@ NDArray IndexSelect(NDArray array, int64_t start, int64_t end);
*/
NDArray Scatter(NDArray array, IdArray indices);
/*!
/**
* @brief Scatter data into the output array.
*
* Equivalent to:
......@@ -186,7 +186,7 @@ NDArray Scatter(NDArray array, IdArray indices);
*/
void Scatter_(IdArray index, NDArray value, NDArray out);
/*!
/**
* @brief Repeat each element a number of times. Equivalent to np.repeat(array, repeats)
* @param array A 1D vector
* @param repeats A 1D integer vector for number of times to repeat for each element in
......@@ -194,7 +194,7 @@ void Scatter_(IdArray index, NDArray value, NDArray out);
*/
NDArray Repeat(NDArray array, IdArray repeats);
/*!
/**
* @brief Relabel the given ids to consecutive ids.
*
* Relabeling is done inplace. The mapping is created from the union
......@@ -211,7 +211,7 @@ NDArray Repeat(NDArray array, IdArray repeats);
*/
IdArray Relabel_(const std::vector<IdArray>& arrays);
/*!
/**
* @brief concatenate the given id arrays to one array
*
* Example:
......@@ -224,12 +224,12 @@ IdArray Relabel_(const std::vector<IdArray>& arrays);
*/
NDArray Concat(const std::vector<IdArray>& arrays);
/*!\brief Return whether the array is a valid 1D int array*/
/** @brief Return whether the array is a valid 1D int array*/
inline bool IsValidIdArray(const dgl::runtime::NDArray& arr) {
return arr->ndim == 1 && arr->dtype.code == kDGLInt;
}
/*!
/**
* @brief Packs a tensor containing padded sequences of variable length.
*
* Similar to \c pack_padded_sequence in PyTorch, except that
......@@ -261,7 +261,7 @@ inline bool IsValidIdArray(const dgl::runtime::NDArray& arr) {
template<typename ValueType>
std::tuple<NDArray, IdArray, IdArray> Pack(NDArray array, ValueType pad_value);
/*!
/**
* @brief Batch-slice a 1D or 2D array, and then pack the list of sliced arrays
* by concatenation.
*
......@@ -291,7 +291,7 @@ std::tuple<NDArray, IdArray, IdArray> Pack(NDArray array, ValueType pad_value);
*/
std::pair<NDArray, IdArray> ConcatSlices(NDArray array, IdArray lengths);
/*!
/**
* @brief Return the cumulative summation (or inclusive sum) of the input array.
*
* The first element out[0] is equal to the first element of the input array
......@@ -307,7 +307,7 @@ std::pair<NDArray, IdArray> ConcatSlices(NDArray array, IdArray lengths);
*/
IdArray CumSum(IdArray array, bool prepend_zero = false);
/*!
/**
* @brief Return the nonzero index.
*
* Only support 1D array. The result index array is in int64.
......@@ -317,7 +317,7 @@ IdArray CumSum(IdArray array, bool prepend_zero = false);
*/
IdArray NonZero(NDArray array);
/*!
/**
* @brief Sort the ID vector in ascending order.
*
* It performs both sort and arg_sort (returning the sorted index). The sorted index
......@@ -334,7 +334,7 @@ IdArray NonZero(NDArray array);
*/
std::pair<IdArray, IdArray> Sort(IdArray array, int num_bits = 0);
/*!
/**
* @brief Return a string that prints out some debug information.
*/
std::string ToDebugString(NDArray array);
......@@ -355,7 +355,7 @@ IdArray VecToIdArray(const std::vector<T>& vec,
return ret.CopyTo(ctx);
}
/*!
/**
* @brief Get the context of the first array, and check if the non-null arrays'
* contexts are the same.
*/
......
include/dgl/aten/coo.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/aten/coo.h
* @brief Common COO operations required by DGL.
......@@ -23,7 +23,7 @@ namespace aten {
struct CSRMatrix;
/*!
/**
* @brief Plain COO structure
*
* The data array stores integer ids for reading edge features.
......@@ -37,21 +37,21 @@ constexpr uint64_t kDGLSerialize_AtenCooMatrixMagic = 0xDD61ffd305dff127;
// TODO(BarclayII): Graph queries on COO formats should support the case where
// data ordered by rows/columns instead of EID.
struct COOMatrix {
/*! @brief the dense shape of the matrix */
/** @brief the dense shape of the matrix */
int64_t num_rows = 0, num_cols = 0;
/*! @brief COO index arrays */
/** @brief COO index arrays */
IdArray row, col;
/*! @brief data index array. When is null, assume it is from 0 to NNZ - 1. */
/** @brief data index array. When is null, assume it is from 0 to NNZ - 1. */
IdArray data;
/*! @brief whether the row indices are sorted */
/** @brief whether the row indices are sorted */
bool row_sorted = false;
/*! @brief whether the column indices per row are sorted */
/** @brief whether the column indices per row are sorted */
bool col_sorted = false;
/*! @brief whether the matrix is in pinned memory */
/** @brief whether the matrix is in pinned memory */
bool is_pinned = false;
/*! @brief default constructor */
/** @brief default constructor */
COOMatrix() = default;
/*! @brief constructor */
/** @brief constructor */
COOMatrix(int64_t nrows, int64_t ncols, IdArray rarr, IdArray carr,
IdArray darr = NullArray(), bool rsorted = false,
bool csorted = false)
......@@ -65,7 +65,7 @@ struct COOMatrix {
CheckValidity();
}
/*! @brief constructor from SparseMatrix object */
/** @brief constructor from SparseMatrix object */
explicit COOMatrix(const SparseMatrix& spmat)
: num_rows(spmat.num_rows),
num_cols(spmat.num_cols),
......@@ -121,7 +121,7 @@ struct COOMatrix {
CHECK_NO_OVERFLOW(row->dtype, num_cols);
}
/*! @brief Return a copy of this matrix on the give device context. */
/** @brief Return a copy of this matrix on the give device context. */
inline COOMatrix CopyTo(const DGLContext &ctx) const {
if (ctx == row->ctx)
return *this;
......@@ -130,7 +130,7 @@ struct COOMatrix {
row_sorted, col_sorted);
}
/*!
/**
* @brief Pin the row, col and data (if not Null) of the matrix.
* @note This is an in-place method. Behavior depends on the current context,
* kDGLCPU: will be pinned;
......@@ -149,7 +149,7 @@ struct COOMatrix {
is_pinned = true;
}
/*!
/**
* @brief Unpin the row, col and data (if not Null) of the matrix.
* @note This is an in-place method. Behavior depends on the current context,
* IsPinned: will be unpinned;
......@@ -167,7 +167,7 @@ struct COOMatrix {
is_pinned = false;
}
/*!
/**
* @brief Record stream for the row, col and data (if not Null) of the matrix.
* @param stream The stream that is using the graph
*/
......@@ -182,28 +182,28 @@ struct COOMatrix {
///////////////////////// COO routines //////////////////////////
/*! @brief Return true if the value (row, col) is non-zero */
/** @brief Return true if the value (row, col) is non-zero */
bool COOIsNonZero(COOMatrix , int64_t row, int64_t col);
/*!
/**
* @brief Batched implementation of COOIsNonZero.
* @note This operator allows broadcasting (i.e, either row or col can be of length 1).
*/
runtime::NDArray COOIsNonZero(COOMatrix , runtime::NDArray row, runtime::NDArray col);
/*! @brief Return the nnz of the given row */
/** @brief Return the nnz of the given row */
int64_t COOGetRowNNZ(COOMatrix , int64_t row);
runtime::NDArray COOGetRowNNZ(COOMatrix , runtime::NDArray row);
/*! @brief Return the data array of the given row */
/** @brief Return the data array of the given row */
std::pair<runtime::NDArray, runtime::NDArray>
COOGetRowDataAndIndices(COOMatrix , int64_t row);
/*! @brief Whether the COO matrix contains data */
/** @brief Whether the COO matrix contains data */
inline bool COOHasData(COOMatrix csr) {
return !IsNullArray(csr.data);
}
/*!
/**
* @brief Check whether the COO is sorted.
*
* It returns two flags: one for whether the row is sorted;
......@@ -214,7 +214,7 @@ inline bool COOHasData(COOMatrix csr) {
*/
std::pair<bool, bool> COOIsSorted(COOMatrix coo);
/*!
/**
* @brief Get the data and the row,col indices for each returned entries.
*
* The operator supports matrix with duplicate entries and all the matched entries
......@@ -230,7 +230,7 @@ std::pair<bool, bool> COOIsSorted(COOMatrix coo);
std::vector<runtime::NDArray> COOGetDataAndIndices(
COOMatrix mat, runtime::NDArray rows, runtime::NDArray cols);
/*! @brief Get data. The return type is an ndarray due to possible duplicate entries. */
/** @brief Get data. The return type is an ndarray due to possible duplicate entries. */
inline runtime::NDArray COOGetAllData(COOMatrix mat, int64_t row, int64_t col) {
IdArray rows = VecToIdArray<int64_t>({row}, mat.row->dtype.bits, mat.row->ctx);
IdArray cols = VecToIdArray<int64_t>({col}, mat.row->dtype.bits, mat.row->ctx);
......@@ -238,7 +238,7 @@ inline runtime::NDArray COOGetAllData(COOMatrix mat, int64_t row, int64_t col) {
return rst[2];
}
/*!
/**
* @brief Get the data for each (row, col) pair.
*
* The operator supports matrix with duplicate entries but only one matched entry
......@@ -254,10 +254,10 @@ inline runtime::NDArray COOGetAllData(COOMatrix mat, int64_t row, int64_t col) {
*/
runtime::NDArray COOGetData(COOMatrix mat, runtime::NDArray rows, runtime::NDArray cols);
/*! @brief Return a transposed COO matrix */
/** @brief Return a transposed COO matrix */
COOMatrix COOTranspose(COOMatrix coo);
/*!
/**
* @brief Convert COO matrix to CSR matrix.
*
* If the input COO matrix does not have data array, the data array of
......@@ -281,7 +281,7 @@ COOMatrix COOTranspose(COOMatrix coo);
*/
CSRMatrix COOToCSR(COOMatrix coo);
/*!
/**
* @brief Slice rows of the given matrix and return.
* @param coo COO matrix
* @param start Start row id (inclusive)
......@@ -290,7 +290,7 @@ CSRMatrix COOToCSR(COOMatrix coo);
COOMatrix COOSliceRows(COOMatrix coo, int64_t start, int64_t end);
COOMatrix COOSliceRows(COOMatrix coo, runtime::NDArray rows);
/*!
/**
* @brief Get the submatrix specified by the row and col ids.
*
* In numpy notation, given matrix M, row index array I, col index array J
......@@ -303,16 +303,16 @@ COOMatrix COOSliceRows(COOMatrix coo, runtime::NDArray rows);
*/
COOMatrix COOSliceMatrix(COOMatrix coo, runtime::NDArray rows, runtime::NDArray cols);
/*! @return True if the matrix has duplicate entries */
/** @return True if the matrix has duplicate entries */
bool COOHasDuplicate(COOMatrix coo);
/*!
/**
* @brief Deduplicate the entries of a sorted COO matrix, replacing the data with the
* number of occurrences of the row-col coordinates.
*/
std::pair<COOMatrix, IdArray> COOCoalesce(COOMatrix coo);
/*!
/**
* @brief Sort the indices of a COO matrix in-place.
*
* The function sorts row indices in ascending order. If sort_column is true,
......@@ -327,7 +327,7 @@ std::pair<COOMatrix, IdArray> COOCoalesce(COOMatrix coo);
*/
void COOSort_(COOMatrix* mat, bool sort_column = false);
/*!
/**
* @brief Sort the indices of a COO matrix.
*
* The function sorts row indices in ascending order. If sort_column is true,
......@@ -352,14 +352,14 @@ inline COOMatrix COOSort(COOMatrix mat, bool sort_column = false) {
return ret;
}
/*!
/**
* @brief Remove entries from COO matrix by entry indices (data indices)
* @return A new COO matrix as well as a mapping from the new COO entries to the old COO
* entries.
*/
COOMatrix COORemove(COOMatrix coo, IdArray entries);
/*!
/**
* @brief Reorder the rows and colmns according to the new row and column order.
* @param csr The input coo matrix.
* @param new_row_ids the new row Ids (the index is the old row Id)
......@@ -367,7 +367,7 @@ COOMatrix COORemove(COOMatrix coo, IdArray entries);
*/
COOMatrix COOReorder(COOMatrix coo, runtime::NDArray new_row_ids, runtime::NDArray new_col_ids);
/*!
/**
* @brief Randomly select a fixed number of non-zero entries along each given row independently.
*
* The function performs random choices along each row independently.
......@@ -410,7 +410,7 @@ COOMatrix COORowWiseSampling(
NDArray prob_or_mask = NDArray(),
bool replace = true);
/*!
/**
* @brief Randomly select a fixed number of non-zero entries for each edge type
* along each given row independently.
*
......@@ -462,7 +462,7 @@ COOMatrix COORowWisePerEtypeSampling(
const std::vector<NDArray>& prob_or_mask,
bool replace = true);
/*!
/**
* @brief Select K non-zero entries with the largest weights along each given row.
*
* The function performs top-k selection along each row independently.
......@@ -506,7 +506,7 @@ COOMatrix COORowWiseTopk(
NDArray weight,
bool ascending = false);
/*!
/**
* @brief Union two COOMatrix into one COOMatrix.
*
* Two Matrix must have the same shape.
......@@ -538,7 +538,7 @@ COOMatrix COORowWiseTopk(
COOMatrix UnionCoo(
const std::vector<COOMatrix>& coos);
/*!
/**
* @brief DisjointUnion a list COOMatrix into one COOMatrix.
*
* Examples:
......@@ -573,7 +573,7 @@ COOMatrix UnionCoo(
COOMatrix DisjointUnionCoo(
const std::vector<COOMatrix>& coos);
/*!
/**
* @brief COOMatrix toSimple.
*
* A = [[0, 0, 0],
......@@ -597,7 +597,7 @@ COOMatrix DisjointUnionCoo(
*/
std::tuple<COOMatrix, IdArray, IdArray> COOToSimple(const COOMatrix& coo);
/*!
/**
* @brief Split a COOMatrix into multiple disjoin components.
*
* Examples:
......@@ -648,7 +648,7 @@ std::vector<COOMatrix> DisjointPartitionCooBySizes(
const std::vector<uint64_t> &src_vertex_cumsum,
const std::vector<uint64_t> &dst_vertex_cumsum);
/*!
/**
* @brief Slice a contiguous chunk from a COOMatrix
*
* Examples:
......@@ -689,7 +689,7 @@ COOMatrix COOSliceContiguousChunk(
const std::vector<uint64_t> &src_vertex_range,
const std::vector<uint64_t> &dst_vertex_range);
/*!
/**
* @brief Create a LineGraph of input coo
*
* A = [[0, 0, 1],
......
include/dgl/aten/csr.h
View file @ bcd37684
This diff is collapsed.
include/dgl/aten/macro.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/aten/macro.h
* @brief Common macros for aten package.
......@@ -9,7 +9,7 @@
///////////////////////// Dispatchers //////////////////////////
/*
/**
* Dispatch according to device:
*
* ATEN_XPU_SWITCH(array->ctx.device_type, XPU, {
......@@ -28,7 +28,7 @@
} \
} while (0)
/*
/**
* Dispatch according to device:
*
* XXX(minjie): temporary macro that allows CUDA operator
......@@ -59,7 +59,7 @@
#define ATEN_XPU_SWITCH_CUDA ATEN_XPU_SWITCH
#endif // DGL_USE_CUDA
/*
/**
* Dispatch according to integral type (either int32 or int64):
*
* ATEN_ID_TYPE_SWITCH(array->dtype, IdType, {
......@@ -81,7 +81,7 @@
} \
} while (0)
/*
/**
* Dispatch according to bits (either int32 or int64):
*
* ATEN_ID_BITS_SWITCH(bits, IdType, {
......@@ -104,7 +104,7 @@
} \
} while (0)
/*
/**
* Dispatch according to float type (either float32 or float64):
*
* ATEN_FLOAT_TYPE_SWITCH(array->dtype, FloatType, {
......@@ -128,7 +128,7 @@
} \
} while (0)
/*
/**
* Dispatch according to float type, including 16bits (float16/bfloat16/float32/float64).
*/
#ifdef DGL_USE_CUDA
......@@ -185,7 +185,7 @@
ATEN_FLOAT_TYPE_SWITCH(val, FloatType, val_name, {__VA_ARGS__})
#endif // DGL_USE_CUDA
/*
/**
* Dispatch according to data type (int32, int64, float32 or float64):
*
* ATEN_DTYPE_SWITCH(array->dtype, DType, {
......@@ -212,7 +212,7 @@
} \
} while (0)
/*
/**
* Dispatch according to data type (int8, uint8, float32 or float64):
*
* ATEN_FLOAT_INT8_UINT8_TYPE_SWITCH(array->dtype, DType, {
......@@ -239,7 +239,7 @@
} \
} while (0)
/*
/**
* Dispatch data type only based on bit-width (8-bit, 16-bit, 32-bit, 64-bit):
*
* ATEN_DTYPE_BITS_ONLY_SWITCH(array->dtype, DType, {
......@@ -268,7 +268,7 @@
} \
} while (0)
/*
/**
* Dispatch according to integral type of CSR graphs.
* Identical to ATEN_ID_TYPE_SWITCH except for a different error message.
*/
......@@ -306,7 +306,7 @@
<< "context as " << (#VAR1) << "(" << (VAR1)->ctx << "). " \
<< "Or " << (#VAR1) << "(" << (VAR1)->ctx << ")" << " is pinned";
/*
/**
* Macro to dispatch according to the context of array and dtype of csr
* to enable CUDA UVA ops.
* Context check is covered here to avoid confusion with CHECK_SAME_CONTEXT.
......
include/dgl/aten/spmat.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/aten/spmat.h
* @brief Sparse matrix definitions
......@@ -14,7 +14,7 @@
namespace dgl {
/*!
/**
* @brief Sparse format.
*/
enum class SparseFormat {
......@@ -23,7 +23,7 @@ enum class SparseFormat {
kCSC = 3,
};
/*!
/**
* @brief Sparse format codes
*/
const dgl_format_code_t ALL_CODE = 0x7;
......
include/dgl/aten/types.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/aten/types.h
* @brief Array and ID types
......@@ -14,7 +14,7 @@ namespace dgl {
typedef uint64_t dgl_id_t;
typedef uint64_t dgl_type_t;
/*! @brief Type for dgl fomrat code, whose binary representation indices
/** @brief Type for dgl fomrat code, whose binary representation indices
* which sparse format is in use and which is not.
*
* Suppose the binary representation is xyz, then
......
include/dgl/base_heterograph.h
View file @ bcd37684
This diff is collapsed.
include/dgl/bcast.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/aten/bcast.h
* @brief Broadcast related function C++ header.
......@@ -14,11 +14,11 @@
using namespace dgl::runtime;
namespace dgl {
/*!
/**
* @brief Broadcast offsets and auxiliary information.
*/
struct BcastOff {
/*!
/**
* @brief offset vector of lhs operand and rhs operand.
* @note lhs_offset[i] indicates the start position of the scalar
* in lhs operand that required to compute the i-th element
......@@ -36,9 +36,9 @@ struct BcastOff {
* rhs array.
*/
std::vector<int64_t> lhs_offset, rhs_offset;
/*! @brief Whether broadcast is required or not. */
/** @brief Whether broadcast is required or not. */
bool use_bcast;
/*!
/**
* @brief Auxiliary information for kernel computation
* @note lhs_len refers to the left hand side operand length.
* e.g. 15 for shape (1, 3, 5)
......@@ -52,7 +52,7 @@ struct BcastOff {
int64_t lhs_len, rhs_len, out_len, reduce_size;
};
/*!
/**
* @brief: Compute broadcast and auxiliary information given operator
* and operands for kernel computation.
* @param op: a string indicates the operator, could be `add`, `sub`,
......
include/dgl/graph.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2018 by Contributors
* @file dgl/graph.h
* @brief DGL graph index class.
......@@ -21,20 +21,20 @@ class Graph;
class GraphOp;
typedef std::shared_ptr<Graph> MutableGraphPtr;
/*! @brief Mutable graph based on adjacency list. */
/** @brief Mutable graph based on adjacency list. */
class Graph : public GraphInterface {
public:
/*! @brief default constructor */
/** @brief default constructor */
Graph() {}
/*! @brief construct a graph from the coo format. */
/** @brief construct a graph from the coo format. */
Graph(IdArray src_ids, IdArray dst_ids, size_t num_nodes);
/*! @brief default copy constructor */
/** @brief default copy constructor */
Graph(const Graph& other) = default;
#ifndef _MSC_VER
/*! @brief default move constructor */
/** @brief default move constructor */
Graph(Graph&& other) = default;
#else
Graph(Graph&& other) {
......@@ -48,13 +48,13 @@ class Graph : public GraphInterface {
}
#endif // _MSC_VER
/*! @brief default assign constructor */
/** @brief default assign constructor */
Graph& operator=(const Graph& other) = default;
/*! @brief default destructor */
/** @brief default destructor */
~Graph() = default;
/*!
/**
* @brief Add vertices to the graph.
* @note Since vertices are integers enumerated from zero, only the number of
* vertices to be added needs to be specified.
......@@ -62,21 +62,21 @@ class Graph : public GraphInterface {
*/
void AddVertices(uint64_t num_vertices) override;
/*!
/**
* @brief Add one edge to the graph.
* @param src The source vertex.
* @param dst The destination vertex.
*/
void AddEdge(dgl_id_t src, dgl_id_t dst) override;
/*!
/**
* @brief Add edges to the graph.
* @param src_ids The source vertex id array.
* @param dst_ids The destination vertex id array.
*/
void AddEdges(IdArray src_ids, IdArray dst_ids) override;
/*!
/**
* @brief Clear the graph. Remove all vertices/edges.
*/
void Clear() override {
......@@ -92,35 +92,35 @@ class Graph : public GraphInterface {
uint8_t NumBits() const override { return 64; }
/*!
/**
* @note not const since we have caches
* @return whether the graph is a multigraph
*/
bool IsMultigraph() const override;
/*!
/**
* @return whether the graph is read-only
*/
bool IsReadonly() const override { return false; }
/*! @return the number of vertices in the graph.*/
/** @return the number of vertices in the graph.*/
uint64_t NumVertices() const override { return adjlist_.size(); }
/*! @return the number of edges in the graph.*/
/** @return the number of edges in the graph.*/
uint64_t NumEdges() const override { return num_edges_; }
/*! @return a 0-1 array indicating whether the given vertices are in the
/** @return a 0-1 array indicating whether the given vertices are in the
* graph.
*/
BoolArray HasVertices(IdArray vids) const override;
/*! @return true if the given edge is in the graph.*/
/** @return true if the given edge is in the graph.*/
bool HasEdgeBetween(dgl_id_t src, dgl_id_t dst) const override;
/*! @return a 0-1 array indicating whether the given edges are in the graph.*/
/** @return a 0-1 array indicating whether the given edges are in the graph.*/
BoolArray HasEdgesBetween(IdArray src_ids, IdArray dst_ids) const override;
/*!
/**
* @brief Find the predecessors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
......@@ -129,7 +129,7 @@ class Graph : public GraphInterface {
*/
IdArray Predecessors(dgl_id_t vid, uint64_t radius = 1) const override;
/*!
/**
* @brief Find the successors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
......@@ -138,7 +138,7 @@ class Graph : public GraphInterface {
*/
IdArray Successors(dgl_id_t vid, uint64_t radius = 1) const override;
/*!
/**
* @brief Get all edge ids between the two given endpoints
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
......@@ -148,7 +148,7 @@ class Graph : public GraphInterface {
*/
IdArray EdgeId(dgl_id_t src, dgl_id_t dst) const override;
/*!
/**
* @brief Get all edge ids between the given endpoint pairs.
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
......@@ -159,7 +159,7 @@ class Graph : public GraphInterface {
*/
EdgeArray EdgeIds(IdArray src, IdArray dst) const override;
/*!
/**
* @brief Find the edge ID and return the pair of endpoints
* @param eid The edge ID
* @return a pair whose first element is the source and the second the
......@@ -169,7 +169,7 @@ class Graph : public GraphInterface {
return std::make_pair(all_edges_src_[eid], all_edges_dst_[eid]);
}
/*!
/**
* @brief Find the edge IDs and return their source and target node IDs.
* @param eids The edge ID array.
* @return EdgeArray containing all edges with id in eid. The order is
......@@ -177,7 +177,7 @@ class Graph : public GraphInterface {
*/
EdgeArray FindEdges(IdArray eids) const override;
/*!
/**
* @brief Get the in edges of the vertex.
* @note The returned dst id array is filled with vid.
* @param vid The vertex id.
......@@ -185,14 +185,14 @@ class Graph : public GraphInterface {
*/
EdgeArray InEdges(dgl_id_t vid) const override;
/*!
/**
* @brief Get the in edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray InEdges(IdArray vids) const override;
/*!
/**
* @brief Get the out edges of the vertex.
* @note The returned src id array is filled with vid.
* @param vid The vertex id.
......@@ -200,14 +200,14 @@ class Graph : public GraphInterface {
*/
EdgeArray OutEdges(dgl_id_t vid) const override;
/*!
/**
* @brief Get the out edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
EdgeArray OutEdges(IdArray vids) const override;
/*!
/**
* @brief Get all the edges in the graph.
* @note If sorted is true, the returned edges list is sorted by their src and
* dst ids. Otherwise, they are in their edge id order.
......@@ -217,7 +217,7 @@ class Graph : public GraphInterface {
*/
EdgeArray Edges(const std::string& order = "") const override;
/*!
/**
* @brief Get the in degree of the given vertex.
* @param vid The vertex id.
* @return the in degree
......@@ -227,14 +227,14 @@ class Graph : public GraphInterface {
return reverse_adjlist_[vid].succ.size();
}
/*!
/**
* @brief Get the in degrees of the given vertices.
* @param vid The vertex id array.
* @return the in degree array
*/
DegreeArray InDegrees(IdArray vids) const override;
/*!
/**
* @brief Get the out degree of the given vertex.
* @param vid The vertex id.
* @return the out degree
......@@ -244,14 +244,14 @@ class Graph : public GraphInterface {
return adjlist_[vid].succ.size();
}
/*!
/**
* @brief Get the out degrees of the given vertices.
* @param vid The vertex id array.
* @return the out degree array
*/
DegreeArray OutDegrees(IdArray vids) const override;
/*!
/**
* @brief Construct the induced subgraph of the given vertices.
*
* The induced subgraph is a subgraph formed by specifying a set of vertices
......@@ -270,7 +270,7 @@ class Graph : public GraphInterface {
*/
Subgraph VertexSubgraph(IdArray vids) const override;
/*!
/**
* @brief Construct the induced edge subgraph of the given edges.
*
* The induced edges subgraph is a subgraph formed by specifying a set of
......@@ -290,7 +290,7 @@ class Graph : public GraphInterface {
Subgraph EdgeSubgraph(
IdArray eids, bool preserve_nodes = false) const override;
/*!
/**
* @brief Return the successor vector
* @param vid The vertex id.
* @return the successor vector
......@@ -301,7 +301,7 @@ class Graph : public GraphInterface {
return DGLIdIters(data, data + size);
}
/*!
/**
* @brief Return the out edge id vector
* @param vid The vertex id.
* @return the out edge id vector
......@@ -312,7 +312,7 @@ class Graph : public GraphInterface {
return DGLIdIters(data, data + size);
}
/*!
/**
* @brief Return the predecessor vector
* @param vid The vertex id.
* @return the predecessor vector
......@@ -323,7 +323,7 @@ class Graph : public GraphInterface {
return DGLIdIters(data, data + size);
}
/*!
/**
* @brief Return the in edge id vector
* @param vid The vertex id.
* @return the in edge id vector
......@@ -334,7 +334,7 @@ class Graph : public GraphInterface {
return DGLIdIters(data, data + size);
}
/*!
/**
* @brief Get the adjacency matrix of the graph.
*
* By default, a row of returned adjacency matrix represents the destination
......@@ -346,10 +346,10 @@ class Graph : public GraphInterface {
std::vector<IdArray> GetAdj(
bool transpose, const std::string& fmt) const override;
/*! @brief Create an empty graph */
/** @brief Create an empty graph */
static MutableGraphPtr Create() { return std::make_shared<Graph>(); }
/*! @brief Create from coo */
/** @brief Create from coo */
static MutableGraphPtr CreateFromCOO(
int64_t num_nodes, IdArray src_ids, IdArray dst_ids) {
return std::make_shared<Graph>(src_ids, dst_ids, num_nodes);
......@@ -357,29 +357,29 @@ class Graph : public GraphInterface {
protected:
friend class GraphOp;
/*! @brief Internal edge list type */
/** @brief Internal edge list type */
struct EdgeList {
/*! @brief successor vertex list */
/** @brief successor vertex list */
std::vector<dgl_id_t> succ;
/*! @brief out edge list */
/** @brief out edge list */
std::vector<dgl_id_t> edge_id;
};
typedef std::vector<EdgeList> AdjacencyList;
/*! @brief adjacency list using vector storage */
/** @brief adjacency list using vector storage */
AdjacencyList adjlist_;
/*! @brief reverse adjacency list using vector storage */
/** @brief reverse adjacency list using vector storage */
AdjacencyList reverse_adjlist_;
/*! @brief all edges' src endpoints in their edge id order */
/** @brief all edges' src endpoints in their edge id order */
std::vector<dgl_id_t> all_edges_src_;
/*! @brief all edges' dst endpoints in their edge id order */
/** @brief all edges' dst endpoints in their edge id order */
std::vector<dgl_id_t> all_edges_dst_;
/*! @brief read only flag */
/** @brief read only flag */
bool read_only_ = false;
/*! @brief number of edges */
/** @brief number of edges */
uint64_t num_edges_ = 0;
};
......
include/dgl/graph_interface.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2018 by Contributors
* @file dgl/graph_interface.h
* @brief DGL graph index class.
......@@ -19,7 +19,7 @@ namespace dgl {
const dgl_id_t DGL_INVALID_ID = static_cast<dgl_id_t>(-1);
/*!
/**
* @brief This class references data in std::vector.
*
* This isn't a STL-style iterator. It provides a STL data container interface.
......@@ -28,9 +28,9 @@ const dgl_id_t DGL_INVALID_ID = static_cast<dgl_id_t>(-1);
*/
class DGLIdIters {
public:
/* !\brief default constructor to create an empty range */
/** @brief default constructor to create an empty range */
DGLIdIters() {}
/* !\brief constructor with given begin and end */
/** @brief constructor with given begin and end */
DGLIdIters(const dgl_id_t *begin, const dgl_id_t *end) {
this->begin_ = begin;
this->end_ = end;
......@@ -44,15 +44,15 @@ class DGLIdIters {
const dgl_id_t *begin_{nullptr}, *end_{nullptr};
};
/*!
/**
* @brief int32 version for DGLIdIters
*
*/
class DGLIdIters32 {
public:
/* !\brief default constructor to create an empty range */
/** @brief default constructor to create an empty range */
DGLIdIters32() {}
/* !\brief constructor with given begin and end */
/** @brief constructor with given begin and end */
DGLIdIters32(const int32_t *begin, const int32_t *end) {
this->begin_ = begin;
this->end_ = end;
......@@ -78,7 +78,7 @@ class GraphRef;
class GraphInterface;
typedef std::shared_ptr<GraphInterface> GraphPtr;
/*!
/**
* @brief dgl graph index interface.
*
* DGL's graph is directed. Vertices are integers enumerated from zero.
......@@ -93,7 +93,7 @@ class GraphInterface : public runtime::Object {
public:
virtual ~GraphInterface() = default;
/*!
/**
* @brief Add vertices to the graph.
* @note Since vertices are integers enumerated from zero, only the number of
* vertices to be added needs to be specified.
......@@ -101,42 +101,42 @@ class GraphInterface : public runtime::Object {
*/
virtual void AddVertices(uint64_t num_vertices) = 0;
/*!
/**
* @brief Add one edge to the graph.
* @param src The source vertex.
* @param dst The destination vertex.
*/
virtual void AddEdge(dgl_id_t src, dgl_id_t dst) = 0;
/*!
/**
* @brief Add edges to the graph.
* @param src_ids The source vertex id array.
* @param dst_ids The destination vertex id array.
*/
virtual void AddEdges(IdArray src_ids, IdArray dst_ids) = 0;
/*!
/**
* @brief Clear the graph. Remove all vertices/edges.
*/
virtual void Clear() = 0;
/*!
/**
* @brief Get the device context of this graph.
*/
virtual DGLContext Context() const = 0;
/*!
/**
* @brief Get the number of integer bits used to store node/edge ids
* (32 or 64).
*/
virtual uint8_t NumBits() const = 0;
/*!
/**
* @return whether the graph is a multigraph
*/
virtual bool IsMultigraph() const = 0;
/*!
/**
* @return whether the graph is unibipartite
*/
virtual bool IsUniBipartite() const {
......@@ -167,32 +167,32 @@ class GraphInterface : public runtime::Object {
return is_unibipartite;
}
/*!
/**
* @return whether the graph is read-only
*/
virtual bool IsReadonly() const = 0;
/*! @return the number of vertices in the graph.*/
/** @return the number of vertices in the graph.*/
virtual uint64_t NumVertices() const = 0;
/*! @return the number of edges in the graph.*/
/** @return the number of edges in the graph.*/
virtual uint64_t NumEdges() const = 0;
/*! @return true if the given vertex is in the graph.*/
/** @return true if the given vertex is in the graph.*/
virtual bool HasVertex(dgl_id_t vid) const { return vid < NumVertices(); }
/*! @return a 0-1 array indicating whether the given vertices are in the
/** @return a 0-1 array indicating whether the given vertices are in the
* graph.
*/
virtual BoolArray HasVertices(IdArray vids) const = 0;
/*! @return true if the given edge is in the graph.*/
/** @return true if the given edge is in the graph.*/
virtual bool HasEdgeBetween(dgl_id_t src, dgl_id_t dst) const = 0;
/*! @return a 0-1 array indicating whether the given edges are in the graph.*/
/** @return a 0-1 array indicating whether the given edges are in the graph.*/
virtual BoolArray HasEdgesBetween(IdArray src_ids, IdArray dst_ids) const = 0;
/*!
/**
* @brief Find the predecessors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
......@@ -201,7 +201,7 @@ class GraphInterface : public runtime::Object {
*/
virtual IdArray Predecessors(dgl_id_t vid, uint64_t radius = 1) const = 0;
/*!
/**
* @brief Find the successors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
......@@ -210,7 +210,7 @@ class GraphInterface : public runtime::Object {
*/
virtual IdArray Successors(dgl_id_t vid, uint64_t radius = 1) const = 0;
/*!
/**
* @brief Get all edge ids between the two given endpoints
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
......@@ -220,7 +220,7 @@ class GraphInterface : public runtime::Object {
*/
virtual IdArray EdgeId(dgl_id_t src, dgl_id_t dst) const = 0;
/*!
/**
* @brief Get all edge ids between the given endpoint pairs.
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
......@@ -231,7 +231,7 @@ class GraphInterface : public runtime::Object {
*/
virtual EdgeArray EdgeIds(IdArray src, IdArray dst) const = 0;
/*!
/**
* @brief Find the edge ID and return the pair of endpoints
* @param eid The edge ID
* @return a pair whose first element is the source and the second the
......@@ -239,7 +239,7 @@ class GraphInterface : public runtime::Object {
*/
virtual std::pair<dgl_id_t, dgl_id_t> FindEdge(dgl_id_t eid) const = 0;
/*!
/**
* @brief Find the edge IDs and return their source and target node IDs.
* @param eids The edge ID array.
* @return EdgeArray containing all edges with id in eid. The order is
......@@ -247,7 +247,7 @@ class GraphInterface : public runtime::Object {
*/
virtual EdgeArray FindEdges(IdArray eids) const = 0;
/*!
/**
* @brief Get the in edges of the vertex.
* @note The returned dst id array is filled with vid.
* @param vid The vertex id.
......@@ -255,14 +255,14 @@ class GraphInterface : public runtime::Object {
*/
virtual EdgeArray InEdges(dgl_id_t vid) const = 0;
/*!
/**
* @brief Get the in edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
virtual EdgeArray InEdges(IdArray vids) const = 0;
/*!
/**
* @brief Get the out edges of the vertex.
* @note The returned src id array is filled with vid.
* @param vid The vertex id.
......@@ -270,14 +270,14 @@ class GraphInterface : public runtime::Object {
*/
virtual EdgeArray OutEdges(dgl_id_t vid) const = 0;
/*!
/**
* @brief Get the out edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
*/
virtual EdgeArray OutEdges(IdArray vids) const = 0;
/*!
/**
* @brief Get all the edges in the graph.
* @note If order is "srcdst", the returned edges list is sorted by their src
* and dst ids. If order is "eid", they are in their edge id order.
......@@ -287,35 +287,35 @@ class GraphInterface : public runtime::Object {
*/
virtual EdgeArray Edges(const std::string &order = "") const = 0;
/*!
/**
* @brief Get the in degree of the given vertex.
* @param vid The vertex id.
* @return the in degree
*/
virtual uint64_t InDegree(dgl_id_t vid) const = 0;
/*!
/**
* @brief Get the in degrees of the given vertices.
* @param vid The vertex id array.
* @return the in degree array
*/
virtual DegreeArray InDegrees(IdArray vids) const = 0;
/*!
/**
* @brief Get the out degree of the given vertex.
* @param vid The vertex id.
* @return the out degree
*/
virtual uint64_t OutDegree(dgl_id_t vid) const = 0;
/*!
/**
* @brief Get the out degrees of the given vertices.
* @param vid The vertex id array.
* @return the out degree array
*/
virtual DegreeArray OutDegrees(IdArray vids) const = 0;
/*!
/**
* @brief Construct the induced subgraph of the given vertices.
*
* The induced subgraph is a subgraph formed by specifying a set of vertices
......@@ -334,7 +334,7 @@ class GraphInterface : public runtime::Object {
*/
virtual Subgraph VertexSubgraph(IdArray vids) const = 0;
/*!
/**
* @brief Construct the induced edge subgraph of the given edges.
*
* The induced edges subgraph is a subgraph formed by specifying a set of
......@@ -356,35 +356,35 @@ class GraphInterface : public runtime::Object {
virtual Subgraph EdgeSubgraph(
IdArray eids, bool preserve_nodes = false) const = 0;
/*!
/**
* @brief Return the successor vector
* @param vid The vertex id.
* @return the successor vector iterator pair.
*/
virtual DGLIdIters SuccVec(dgl_id_t vid) const = 0;
/*!
/**
* @brief Return the out edge id vector
* @param vid The vertex id.
* @return the out edge id vector iterator pair.
*/
virtual DGLIdIters OutEdgeVec(dgl_id_t vid) const = 0;
/*!
/**
* @brief Return the predecessor vector
* @param vid The vertex id.
* @return the predecessor vector iterator pair.
*/
virtual DGLIdIters PredVec(dgl_id_t vid) const = 0;
/*!
/**
* @brief Return the in edge id vector
* @param vid The vertex id.
* @return the in edge id vector iterator pair.
*/
virtual DGLIdIters InEdgeVec(dgl_id_t vid) const = 0;
/*!
/**
* @brief Get the adjacency matrix of the graph.
*
* By default, a row of returned adjacency matrix represents the destination
......@@ -403,7 +403,7 @@ class GraphInterface : public runtime::Object {
virtual std::vector<IdArray> GetAdj(
bool transpose, const std::string &fmt) const = 0;
/*!
/**
* @brief Sort the columns in CSR.
*
* This sorts the columns in each row based on the column Ids.
......@@ -418,17 +418,17 @@ class GraphInterface : public runtime::Object {
// Define GraphRef
DGL_DEFINE_OBJECT_REF(GraphRef, GraphInterface);
/*! @brief Subgraph data structure */
/** @brief Subgraph data structure */
struct Subgraph : public runtime::Object {
/*! @brief The graph. */
/** @brief The graph. */
GraphPtr graph;
/*!
/**
* @brief The induced vertex ids.
* @note This is also a map from the new vertex id to the vertex id in the
* parent graph.
*/
IdArray induced_vertices;
/*!
/**
* @brief The induced edge ids.
* @note This is also a map from the new edge id to the edge id in the parent
* graph.
......@@ -439,21 +439,21 @@ struct Subgraph : public runtime::Object {
DGL_DECLARE_OBJECT_TYPE_INFO(Subgraph, runtime::Object);
};
/*! @brief Subgraph data structure for negative subgraph */
/** @brief Subgraph data structure for negative subgraph */
struct NegSubgraph : public Subgraph {
/*! @brief The existence of the negative edges in the parent graph. */
/** @brief The existence of the negative edges in the parent graph. */
IdArray exist;
/*! @brief The Ids of head nodes */
/** @brief The Ids of head nodes */
IdArray head_nid;
/*! @brief The Ids of tail nodes */
/** @brief The Ids of tail nodes */
IdArray tail_nid;
};
/*! @brief Subgraph data structure for halo subgraph */
/** @brief Subgraph data structure for halo subgraph */
struct HaloSubgraph : public Subgraph {
/*! @brief Indicate if a node belongs to the partition. */
/** @brief Indicate if a node belongs to the partition. */
IdArray inner_nodes;
};
......
include/dgl/graph_op.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2018 by Contributors
* @file dgl/graph_op.h
* @brief Operations on graph index.
......@@ -15,7 +15,7 @@ namespace dgl {
class GraphOp {
public:
/*!
/**
* @brief Return a new graph with all the edges reversed.
*
* The returned graph preserves the vertex and edge index in the original
......@@ -25,7 +25,7 @@ class GraphOp {
*/
static GraphPtr Reverse(GraphPtr graph);
/*!
/**
* @brief Return the line graph.
*
* If i~j and j~i are two edges in original graph G, then
......@@ -38,7 +38,7 @@ class GraphOp {
*/
static GraphPtr LineGraph(GraphPtr graph, bool backtracking);
/*!
/**
* @brief Return a disjoint union of the input graphs.
*
* The new graph will include all the nodes/edges in the given graphs.
......@@ -55,7 +55,7 @@ class GraphOp {
*/
static GraphPtr DisjointUnion(std::vector<GraphPtr> graphs);
/*!
/**
* @brief Partition the graph into several subgraphs.
*
* This is a reverse operation of DisjointUnion. The graph will be partitioned
......@@ -72,7 +72,7 @@ class GraphOp {
static std::vector<GraphPtr> DisjointPartitionByNum(
GraphPtr graph, int64_t num);
/*!
/**
* @brief Partition the graph into several subgraphs.
*
* This is a reverse operation of DisjointUnion. The graph will be partitioned
......@@ -89,7 +89,7 @@ class GraphOp {
static std::vector<GraphPtr> DisjointPartitionBySizes(
GraphPtr graph, IdArray sizes);
/*!
/**
* @brief Map vids in the parent graph to the vids in the subgraph.
*
* If the Id doesn't exist in the subgraph, -1 will be used.
......@@ -102,7 +102,7 @@ class GraphOp {
*/
static IdArray MapParentIdToSubgraphId(IdArray parent_vid_map, IdArray query);
/*!
/**
* @brief Expand an Id array based on the offset array.
*
* For example,
......@@ -118,14 +118,14 @@ class GraphOp {
*/
static IdArray ExpandIds(IdArray ids, IdArray offset);
/*!
/**
* @brief Convert the graph to a simple graph.
* @param graph The input graph.
* @return a new immutable simple graph with no multi-edge.
*/
static GraphPtr ToSimpleGraph(GraphPtr graph);
/*!
/**
* @brief Convert the graph to a mutable bidirected graph.
*
* If the original graph has m edges for i -> j and n edges for
......@@ -137,7 +137,7 @@ class GraphOp {
*/
static GraphPtr ToBidirectedMutableGraph(GraphPtr graph);
/*!
/**
* @brief Same as BidirectedMutableGraph except that the returned graph is
* immutable.
* @param graph The input graph.
......@@ -145,7 +145,7 @@ class GraphOp {
* graph.
*/
static GraphPtr ToBidirectedImmutableGraph(GraphPtr graph);
/*!
/**
* @brief Same as BidirectedMutableGraph except that the returned graph is
* immutable and call gk_csr_MakeSymmetric in GKlib. This is more efficient
* than ToBidirectedImmutableGraph. It return a null pointer if the conversion
......@@ -156,7 +156,7 @@ class GraphOp {
*/
static GraphPtr ToBidirectedSimpleImmutableGraph(ImmutableGraphPtr ig);
/*!
/**
* @brief Get a induced subgraph with HALO nodes.
* The HALO nodes are the ones that can be reached from `nodes` within
* `num_hops`.
......@@ -168,7 +168,7 @@ class GraphOp {
static HaloSubgraph GetSubgraphWithHalo(
GraphPtr graph, IdArray nodes, int num_hops);
/*!
/**
* @brief Reorder the nodes in the immutable graph.
* @param graph The input graph.
* @param new_order The node Ids in the new graph. The index in `new_order` is
......
include/dgl/graph_serializer.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2018 by Contributors
* @file graph/graph_serializer.cc
* @brief DGL serializer APIs
......
include/dgl/graph_traversal.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/graph_traversal.h
* @brief common graph traversal operations
......@@ -12,7 +12,7 @@
namespace dgl {
///////////////////////// Graph Traverse routines //////////////////////////
/*!
/**
* @brief Class for representing frontiers.
*
* Each frontier is a list of nodes/edges (specified by their ids).
......@@ -20,22 +20,22 @@ namespace dgl {
* value).
*/
struct Frontiers {
/*!\brief a vector store for the nodes/edges in all the frontiers */
/** @brief a vector store for the nodes/edges in all the frontiers */
IdArray ids;
/*!
/**
* @brief a vector store for node/edge tags. Dtype is int64.
* Empty if no tags are requested
*/
IdArray tags;
/*!\brief a section vector to indicate each frontier Dtype is int64. */
/** @brief a section vector to indicate each frontier Dtype is int64. */
IdArray sections;
};
namespace aten {
/*!
/**
* @brief Traverse the graph in a breadth-first-search (BFS) order.
*
* @param csr The input csr matrix.
......@@ -44,7 +44,7 @@ namespace aten {
*/
Frontiers BFSNodesFrontiers(const CSRMatrix& csr, IdArray source);
/*!
/**
* @brief Traverse the graph in a breadth-first-search (BFS) order, returning
* the edges of the BFS tree.
*
......@@ -54,7 +54,7 @@ Frontiers BFSNodesFrontiers(const CSRMatrix& csr, IdArray source);
*/
Frontiers BFSEdgesFrontiers(const CSRMatrix& csr, IdArray source);
/*!
/**
* @brief Traverse the graph in topological order.
*
* @param csr The input csr matrix.
......@@ -62,7 +62,7 @@ Frontiers BFSEdgesFrontiers(const CSRMatrix& csr, IdArray source);
*/
Frontiers TopologicalNodesFrontiers(const CSRMatrix& csr);
/*!
/**
* @brief Traverse the graph in a depth-first-search (DFS) order.
*
* @param csr The input csr matrix.
......@@ -71,7 +71,7 @@ Frontiers TopologicalNodesFrontiers(const CSRMatrix& csr);
*/
Frontiers DGLDFSEdges(const CSRMatrix& csr, IdArray source);
/*!
/**
* @brief Traverse the graph in a depth-first-search (DFS) order and return the
* recorded edge tag if return_labels is specified.
*
......
include/dgl/immutable_graph.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2018 by Contributors
* @file dgl/immutable_graph.h
* @brief DGL immutable graph index class.
......@@ -29,7 +29,7 @@ typedef std::shared_ptr<COO> COOPtr;
class ImmutableGraph;
typedef std::shared_ptr<ImmutableGraph> ImmutableGraphPtr;
/*!
/**
* @brief Graph class stored using CSR structure.
*/
class CSR : public GraphInterface {
......@@ -180,37 +180,37 @@ class CSR : public GraphInterface {
return {adj_.indptr, adj_.indices, adj_.data};
}
/*! @brief Indicate whether this uses shared memory. */
/** @brief Indicate whether this uses shared memory. */
bool IsSharedMem() const { return !shared_mem_name_.empty(); }
/*! @brief Return the reverse of this CSR graph (i.e, a CSC graph) */
/** @brief Return the reverse of this CSR graph (i.e, a CSC graph) */
CSRPtr Transpose() const;
/*! @brief Convert this CSR to COO */
/** @brief Convert this CSR to COO */
COOPtr ToCOO() const;
/*!
/**
* @return the csr matrix that represents this graph.
* @note The csr matrix shares the storage with this graph.
* The data field of the CSR matrix stores the edge ids.
*/
aten::CSRMatrix ToCSRMatrix() const { return adj_; }
/*!
/**
* @brief Copy the data to another context.
* @param ctx The target context.
* @return The graph under another context.
*/
CSR CopyTo(const DGLContext &ctx) const;
/*!
/**
* @brief Copy data to shared memory.
* @param name The name of the shared memory.
* @return The graph in the shared memory
*/
CSR CopyToSharedMem(const std::string &name) const;
/*!
/**
* @brief Convert the graph to use the given number of bits for storage.
* @param bits The new number of integer bits (32 or 64).
* @return The graph with new bit size storage.
......@@ -225,10 +225,10 @@ class CSR : public GraphInterface {
IdArray edge_ids() const { return adj_.data; }
/*! @return Load CSR from stream */
/** @return Load CSR from stream */
bool Load(dmlc::Stream *fs);
/*! @return Save CSR to stream */
/** @return Save CSR to stream */
void Save(dmlc::Stream *fs) const;
void SortCSR() override {
......@@ -239,7 +239,7 @@ class CSR : public GraphInterface {
private:
friend class Serializer;
/*! @brief private default constructor */
/** @brief private default constructor */
CSR() { adj_.sorted = false; }
// The internal CSR adjacency matrix.
// The data field stores edge ids.
......@@ -424,43 +424,43 @@ class COO : public GraphInterface {
}
}
/*! @brief Return the transpose of this COO */
/** @brief Return the transpose of this COO */
COOPtr Transpose() const {
return COOPtr(new COO(adj_.num_rows, adj_.col, adj_.row));
}
/*! @brief Convert this COO to CSR */
/** @brief Convert this COO to CSR */
CSRPtr ToCSR() const;
/*!
/**
* @brief Get the coo matrix that represents this graph.
* @note The coo matrix shares the storage with this graph.
* The data field of the coo matrix is none.
*/
aten::COOMatrix ToCOOMatrix() const { return adj_; }
/*!
/**
* @brief Copy the data to another context.
* @param ctx The target context.
* @return The graph under another context.
*/
COO CopyTo(const DGLContext &ctx) const;
/*!
/**
* @brief Copy data to shared memory.
* @param name The name of the shared memory.
* @return The graph in the shared memory
*/
COO CopyToSharedMem(const std::string &name) const;
/*!
/**
* @brief Convert the graph to use the given number of bits for storage.
* @param bits The new number of integer bits (32 or 64).
* @return The graph with new bit size storage.
*/
COO AsNumBits(uint8_t bits) const;
/*! @brief Indicate whether this uses shared memory. */
/** @brief Indicate whether this uses shared memory. */
bool IsSharedMem() const { return false; }
// member getters
......@@ -470,7 +470,7 @@ class COO : public GraphInterface {
IdArray dst() const { return adj_.col; }
private:
/* !\brief private default constructor */
/** @brief private default constructor */
COO() {}
// The internal COO adjacency matrix.
......@@ -478,17 +478,17 @@ class COO : public GraphInterface {
aten::COOMatrix adj_;
};
/*!
/**
* @brief DGL immutable graph index class.
*
* DGL's graph is directed. Vertices are integers enumerated from zero.
*/
class ImmutableGraph : public GraphInterface {
public:
/*! @brief Construct an immutable graph from the COO format. */
/** @brief Construct an immutable graph from the COO format. */
explicit ImmutableGraph(COOPtr coo) : coo_(coo) {}
/*!
/**
* @brief Construct an immutable graph from the CSR format.
*
* For a single graph, we need two CSRs, one stores the in-edges of vertices
......@@ -506,14 +506,14 @@ class ImmutableGraph : public GraphInterface {
CHECK(in_csr_ || out_csr_) << "Both CSR are missing.";
}
/*! @brief Construct an immutable graph from one CSR. */
/** @brief Construct an immutable graph from one CSR. */
explicit ImmutableGraph(CSRPtr csr) : out_csr_(csr) {}
/*! @brief default copy constructor */
/** @brief default copy constructor */
ImmutableGraph(const ImmutableGraph &other) = default;
#ifndef _MSC_VER
/*! @brief default move constructor */
/** @brief default move constructor */
ImmutableGraph(ImmutableGraph &&other) = default;
#else
ImmutableGraph(ImmutableGraph &&other) {
......@@ -526,10 +526,10 @@ class ImmutableGraph : public GraphInterface {
}
#endif // _MSC_VER
/*! @brief default assign constructor */
/** @brief default assign constructor */
ImmutableGraph &operator=(const ImmutableGraph &other) = default;
/*! @brief default destructor */
/** @brief default destructor */
~ImmutableGraph() = default;
void AddVertices(uint64_t num_vertices) override {
......@@ -552,13 +552,13 @@ class ImmutableGraph : public GraphInterface {
uint8_t NumBits() const override { return AnyGraph()->NumBits(); }
/*!
/**
* @note not const since we have caches
* @return whether the graph is a multigraph
*/
bool IsMultigraph() const override { return AnyGraph()->IsMultigraph(); }
/*!
/**
* @return whether the graph is read-only
*/
bool IsReadonly() const override { return true; }
......@@ -577,18 +577,18 @@ class ImmutableGraph : public GraphInterface {
return is_unibipartite_;
}
/*! @return the number of vertices in the graph.*/
/** @return the number of vertices in the graph.*/
uint64_t NumVertices() const override { return AnyGraph()->NumVertices(); }
/*! @return the number of edges in the graph.*/
/** @return the number of edges in the graph.*/
uint64_t NumEdges() const override { return AnyGraph()->NumEdges(); }
/*! @return true if the given vertex is in the graph.*/
/** @return true if the given vertex is in the graph.*/
bool HasVertex(dgl_id_t vid) const override { return vid < NumVertices(); }
BoolArray HasVertices(IdArray vids) const override;
/*! @return true if the given edge is in the graph.*/
/** @return true if the given edge is in the graph.*/
bool HasEdgeBetween(dgl_id_t src, dgl_id_t dst) const override {
if (in_csr_) {
return in_csr_->HasEdgeBetween(dst, src);
......@@ -605,7 +605,7 @@ class ImmutableGraph : public GraphInterface {
}
}
/*!
/**
* @brief Find the predecessors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
......@@ -616,7 +616,7 @@ class ImmutableGraph : public GraphInterface {
return GetInCSR()->Successors(vid, radius);
}
/*!
/**
* @brief Find the successors of a vertex.
* @param vid The vertex id.
* @param radius The radius of the neighborhood. Default is immediate neighbor
......@@ -627,7 +627,7 @@ class ImmutableGraph : public GraphInterface {
return GetOutCSR()->Successors(vid, radius);
}
/*!
/**
* @brief Get all edge ids between the two given endpoints
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
......@@ -643,7 +643,7 @@ class ImmutableGraph : public GraphInterface {
}
}
/*!
/**
* @brief Get all edge ids between the given endpoint pairs.
* @note Edges are associated with an integer id start from zero.
* The id is assigned when the edge is being added to the graph.
......@@ -661,7 +661,7 @@ class ImmutableGraph : public GraphInterface {
}
}
/*!
/**
* @brief Find the edge ID and return the pair of endpoints
* @param eid The edge ID
* @return a pair whose first element is the source and the second the
......@@ -671,7 +671,7 @@ class ImmutableGraph : public GraphInterface {
return GetCOO()->FindEdge(eid);
}
/*!
/**
* @brief Find the edge IDs and return their source and target node IDs.
* @param eids The edge ID array.
* @return EdgeArray containing all edges with id in eid. The order is
......@@ -681,7 +681,7 @@ class ImmutableGraph : public GraphInterface {
return GetCOO()->FindEdges(eids);
}
/*!
/**
* @brief Get the in edges of the vertex.
* @note The returned dst id array is filled with vid.
* @param vid The vertex id.
......@@ -692,7 +692,7 @@ class ImmutableGraph : public GraphInterface {
return {ret.dst, ret.src, ret.id};
}
/*!
/**
* @brief Get the in edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
......@@ -702,7 +702,7 @@ class ImmutableGraph : public GraphInterface {
return {ret.dst, ret.src, ret.id};
}
/*!
/**
* @brief Get the out edges of the vertex.
* @note The returned src id array is filled with vid.
* @param vid The vertex id.
......@@ -712,7 +712,7 @@ class ImmutableGraph : public GraphInterface {
return GetOutCSR()->OutEdges(vid);
}
/*!
/**
* @brief Get the out edges of the vertices.
* @param vids The vertex id array.
* @return the id arrays of the two endpoints of the edges.
......@@ -721,7 +721,7 @@ class ImmutableGraph : public GraphInterface {
return GetOutCSR()->OutEdges(vids);
}
/*!
/**
* @brief Get all the edges in the graph.
* @note If sorted is true, the returned edges list is sorted by their src and
* dst ids. Otherwise, they are in their edge id order.
......@@ -731,7 +731,7 @@ class ImmutableGraph : public GraphInterface {
*/
EdgeArray Edges(const std::string &order = "") const override;
/*!
/**
* @brief Get the in degree of the given vertex.
* @param vid The vertex id.
* @return the in degree
......@@ -740,7 +740,7 @@ class ImmutableGraph : public GraphInterface {
return GetInCSR()->OutDegree(vid);
}
/*!
/**
* @brief Get the in degrees of the given vertices.
* @param vid The vertex id array.
* @return the in degree array
......@@ -749,7 +749,7 @@ class ImmutableGraph : public GraphInterface {
return GetInCSR()->OutDegrees(vids);
}
/*!
/**
* @brief Get the out degree of the given vertex.
* @param vid The vertex id.
* @return the out degree
......@@ -758,7 +758,7 @@ class ImmutableGraph : public GraphInterface {
return GetOutCSR()->OutDegree(vid);
}
/*!
/**
* @brief Get the out degrees of the given vertices.
* @param vid The vertex id array.
* @return the out degree array
......@@ -767,7 +767,7 @@ class ImmutableGraph : public GraphInterface {
return GetOutCSR()->OutDegrees(vids);
}
/*!
/**
* @brief Construct the induced subgraph of the given vertices.
*
* The induced subgraph is a subgraph formed by specifying a set of vertices
......@@ -786,7 +786,7 @@ class ImmutableGraph : public GraphInterface {
*/
Subgraph VertexSubgraph(IdArray vids) const override;
/*!
/**
* @brief Construct the induced edge subgraph of the given edges.
*
* The induced edges subgraph is a subgraph formed by specifying a set of
......@@ -806,7 +806,7 @@ class ImmutableGraph : public GraphInterface {
Subgraph EdgeSubgraph(
IdArray eids, bool preserve_nodes = false) const override;
/*!
/**
* @brief Return the successor vector
* @param vid The vertex id.
* @return the successor vector
......@@ -815,7 +815,7 @@ class ImmutableGraph : public GraphInterface {
return GetOutCSR()->SuccVec(vid);
}
/*!
/**
* @brief Return the out edge id vector
* @param vid The vertex id.
* @return the out edge id vector
......@@ -824,7 +824,7 @@ class ImmutableGraph : public GraphInterface {
return GetOutCSR()->OutEdgeVec(vid);
}
/*!
/**
* @brief Return the predecessor vector
* @param vid The vertex id.
* @return the predecessor vector
......@@ -833,7 +833,7 @@ class ImmutableGraph : public GraphInterface {
return GetInCSR()->SuccVec(vid);
}
/*!
/**
* @brief Return the in edge id vector
* @param vid The vertex id.
* @return the in edge id vector
......@@ -842,7 +842,7 @@ class ImmutableGraph : public GraphInterface {
return GetInCSR()->OutEdgeVec(vid);
}
/*!
/**
* @brief Get the adjacency matrix of the graph.
*
* By default, a row of returned adjacency matrix represents the destination
......@@ -854,28 +854,28 @@ class ImmutableGraph : public GraphInterface {
std::vector<IdArray> GetAdj(
bool transpose, const std::string &fmt) const override;
/* !\brief Return in csr. If not exist, transpose the other one.*/
/** @brief Return in csr. If not exist, transpose the other one.*/
CSRPtr GetInCSR() const;
/* !\brief Return out csr. If not exist, transpose the other one.*/
/** @brief Return out csr. If not exist, transpose the other one.*/
CSRPtr GetOutCSR() const;
/* !\brief Return coo. If not exist, create from csr.*/
/** @brief Return coo. If not exist, create from csr.*/
COOPtr GetCOO() const;
/*! @brief Create an immutable graph from CSR. */
/** @brief Create an immutable graph from CSR. */
static ImmutableGraphPtr CreateFromCSR(
IdArray indptr, IdArray indices, IdArray edge_ids,
const std::string &edge_dir);
static ImmutableGraphPtr CreateFromCSR(const std::string &shared_mem_name);
/*! @brief Create an immutable graph from COO. */
/** @brief Create an immutable graph from COO. */
static ImmutableGraphPtr CreateFromCOO(
int64_t num_vertices, IdArray src, IdArray dst, bool row_osrted = false,
bool col_sorted = false);
/*!
/**
* @brief Convert the given graph to an immutable graph.
*
* If the graph is already an immutable graph. The result graph will share
......@@ -886,14 +886,14 @@ class ImmutableGraph : public GraphInterface {
*/
static ImmutableGraphPtr ToImmutable(GraphPtr graph);
/*!
/**
* @brief Copy the data to another context.
* @param ctx The target context.
* @return The graph under another context.
*/
static ImmutableGraphPtr CopyTo(ImmutableGraphPtr g, const DGLContext &ctx);
/*!
/**
* @brief Copy data to shared memory.
* @param name The name of the shared memory.
* @return The graph in the shared memory
......@@ -901,14 +901,14 @@ class ImmutableGraph : public GraphInterface {
static ImmutableGraphPtr CopyToSharedMem(
ImmutableGraphPtr g, const std::string &name);
/*!
/**
* @brief Convert the graph to use the given number of bits for storage.
* @param bits The new number of integer bits (32 or 64).
* @return The graph with new bit size storage.
*/
static ImmutableGraphPtr AsNumBits(ImmutableGraphPtr g, uint8_t bits);
/*!
/**
* @brief Return a new graph with all the edges reversed.
*
* The returned graph preserves the vertex and edge index in the original
......@@ -918,10 +918,10 @@ class ImmutableGraph : public GraphInterface {
*/
ImmutableGraphPtr Reverse() const;
/*! @return Load ImmutableGraph from stream, using out csr */
/** @return Load ImmutableGraph from stream, using out csr */
bool Load(dmlc::Stream *fs);
/*! @return Save ImmutableGraph to stream, using out csr */
/** @return Save ImmutableGraph to stream, using out csr */
void Save(dmlc::Stream *fs) const;
void SortCSR() override {
......@@ -933,17 +933,17 @@ class ImmutableGraph : public GraphInterface {
bool HasOutCSR() const { return out_csr_ != NULL; }
/*! @brief Cast this graph to a heterograph */
/** @brief Cast this graph to a heterograph */
HeteroGraphPtr AsHeteroGraph() const;
protected:
friend class Serializer;
friend class UnitGraph;
/* !\brief internal default constructor */
/** @brief internal default constructor */
ImmutableGraph() {}
/* !\brief internal constructor for all the members */
/** @brief internal constructor for all the members */
ImmutableGraph(CSRPtr in_csr, CSRPtr out_csr, COOPtr coo)
: in_csr_(in_csr), out_csr_(out_csr), coo_(coo) {
CHECK(AnyGraph()) << "At least one graph structure should exist.";
......@@ -956,7 +956,7 @@ class ImmutableGraph : public GraphInterface {
this->shared_mem_name_ = shared_mem_name;
}
/* !\brief return pointer to any available graph structure */
/** @brief return pointer to any available graph structure */
GraphPtr AnyGraph() const {
if (in_csr_) {
return in_csr_;
......
include/dgl/kernel.h
View file @ bcd37684
/*!
/**
* Copyright (c) 2020 by Contributors
* @file dgl/aten/kernel.h
* @brief Sparse matrix operators.
......@@ -17,7 +17,7 @@
namespace dgl {
namespace aten {
/*!
/**
* @brief Generalized Sparse Matrix-Matrix Multiplication.
* @param op The binary operator, could be `add`, `sub', `mul`, 'div',
* `copy_u`, `copy_e'.
......@@ -34,7 +34,7 @@ void SpMM(
const std::string& op, const std::string& reduce, HeteroGraphPtr graph,
NDArray ufeat, NDArray efeat, NDArray out, std::vector<NDArray> out_aux);
/*!
/**
* @brief Generalized Sampled Dense-Dense Matrix Multiplication.
* @param op The binary operator, could be `add`, `sub', `mul`, 'div',
* `dot`, `copy_u`, `copy_e'.
......@@ -47,7 +47,7 @@ void SDDMM(
const std::string& op, HeteroGraphPtr graph, NDArray ufeat, NDArray efeat,
NDArray out);
/*!
/**
* @brief Sparse-sparse matrix multiplication.
*
* The sparse matrices must have scalar weights (i.e. \a A_weights and \a
......@@ -56,7 +56,7 @@ void SDDMM(
std::pair<CSRMatrix, NDArray> CSRMM(
CSRMatrix A, NDArray A_weights, CSRMatrix B, NDArray B_weights);
/*!
/**
* @brief Summing up a list of sparse matrices.
*
* The sparse matrices must have scalar weights (i.e. the arrays in \a A_weights
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment