From df7280b5f6d3c85a4b7e6f845e8e042a96b5c7a4 Mon Sep 17 00:00:00 2001 From: pe4eniks Date: Thu, 2 Nov 2023 10:06:03 -0700 Subject: [PATCH] Documentation fixes (#3092) Summary: As a follow-up to this issue https://github.com/facebookresearch/faiss/issues/3086, I've fixed some bugs in the doxygen-generated documentation. Pull Request resolved: https://github.com/facebookresearch/faiss/pull/3092 Reviewed By: pemazare Differential Revision: D50595811 Pulled By: mdouze fbshipit-source-id: 74797d3f2594a20597e1eb6545e91f6eac6d035d --- faiss/Index.h | 21 ++++++++++++++++++--- faiss/IndexFlat.h | 7 ++++++- faiss/IndexFlatCodes.h | 1 - faiss/IndexPQ.h | 5 +---- 4 files changed, 25 insertions(+), 9 deletions(-) diff --git a/faiss/Index.h b/faiss/Index.h index d73a684f54..4b4b302b47 100644 --- a/faiss/Index.h +++ b/faiss/Index.h @@ -99,6 +99,7 @@ struct Index { * Vectors are implicitly assigned labels ntotal .. ntotal + n - 1 * This function slices the input vectors in chunks smaller than * blocksize_add and calls add_core. + * @param n number of vectors * @param x input matrix, size n * d */ virtual void add(idx_t n, const float* x) = 0; @@ -108,7 +109,9 @@ struct Index { * The default implementation fails with an assertion, as it is * not supported by all indexes. * - * @param xids if non-null, ids to store for the vectors (size n) + * @param n number of vectors + * @param x input vectors, size n * d + * @param xids if non-null, ids to store for the vectors (size n) */ virtual void add_with_ids(idx_t n, const float* x, const idx_t* xids); @@ -117,9 +120,11 @@ struct Index { * return at most k vectors. If there are not enough results for a * query, the result array is padded with -1s. * + * @param n number of vectors * @param x input vectors to search, size n * d - * @param labels output labels of the NNs, size n*k + * @param k number of extracted vectors * @param distances output pairwise distances, size n*k + * @param labels output labels of the NNs, size n*k */ virtual void search( idx_t n, @@ -135,6 +140,7 @@ struct Index { * indexes do not implement the range_search (only the k-NN search * is mandatory). * + * @param n number of vectors * @param x input vectors to search, size n * d * @param radius search radius * @param result result table @@ -149,8 +155,10 @@ struct Index { /** return the indexes of the k vectors closest to the query x. * * This function is identical as search but only return labels of neighbors. + * @param n number of vectors * @param x input vectors to search, size n * d * @param labels output labels of the NNs, size n*k + * @param k number of nearest neighbours */ virtual void assign(idx_t n, const float* x, idx_t* labels, idx_t k = 1) const; @@ -174,7 +182,7 @@ struct Index { /** Reconstruct several stored vectors (or an approximation if lossy coding) * * this function may not be defined for some indexes - * @param n number of vectors to reconstruct + * @param n number of vectors to reconstruct * @param keys ids of the vectors to reconstruct (size n) * @param recons reconstucted vector (size n * d) */ @@ -184,6 +192,8 @@ struct Index { /** Reconstruct vectors i0 to i0 + ni - 1 * * this function may not be defined for some indexes + * @param i0 index of the first vector in the sequence + * @param ni number of vectors in the sequence * @param recons reconstucted vector (size ni * d) */ virtual void reconstruct_n(idx_t i0, idx_t ni, float* recons) const; @@ -194,6 +204,11 @@ struct Index { * If there are not enough results for a query, the resulting arrays * is padded with -1s. * + * @param n number of vectors + * @param x input vectors to search, size n * d + * @param k number of extracted vectors + * @param distances output pairwise distances, size n*k + * @param labels output labels of the NNs, size n*k * @param recons reconstructed vectors size (n, k, d) **/ virtual void search_and_reconstruct( diff --git a/faiss/IndexFlat.h b/faiss/IndexFlat.h index c2f6eafed7..ac15cae467 100644 --- a/faiss/IndexFlat.h +++ b/faiss/IndexFlat.h @@ -18,7 +18,9 @@ namespace faiss { /** Index that stores the full vectors and performs exhaustive search */ struct IndexFlat : IndexFlatCodes { - explicit IndexFlat(idx_t d, MetricType metric = METRIC_L2); + explicit IndexFlat( + idx_t d, ///< dimensionality of the input vectors + MetricType metric = METRIC_L2); void search( idx_t n, @@ -82,6 +84,9 @@ struct IndexFlatL2 : IndexFlat { // and l2 norms. std::vector cached_l2norms; + /** + * @param d dimensionality of the input vectors + */ explicit IndexFlatL2(idx_t d) : IndexFlat(d, METRIC_L2) {} IndexFlatL2() {} diff --git a/faiss/IndexFlatCodes.h b/faiss/IndexFlatCodes.h index 687558123f..cd43e47ecc 100644 --- a/faiss/IndexFlatCodes.h +++ b/faiss/IndexFlatCodes.h @@ -34,7 +34,6 @@ struct IndexFlatCodes : Index { void reset() override; - /// reconstruction using the codec interface void reconstruct_n(idx_t i0, idx_t ni, float* recons) const override; void reconstruct(idx_t key, float* recons) const override; diff --git a/faiss/IndexPQ.h b/faiss/IndexPQ.h index a972a7a2b9..c806c7f186 100644 --- a/faiss/IndexPQ.h +++ b/faiss/IndexPQ.h @@ -31,10 +31,7 @@ struct IndexPQ : IndexFlatCodes { * @param M number of subquantizers * @param nbits number of bit per subvector index */ - IndexPQ(int d, ///< dimensionality of the input vectors - size_t M, ///< number of subquantizers - size_t nbits, ///< number of bit per subvector index - MetricType metric = METRIC_L2); + IndexPQ(int d, size_t M, size_t nbits, MetricType metric = METRIC_L2); IndexPQ();