Documentation fixes (facebookresearch#3092)

Summary:
As a follow-up to this issue facebookresearch#3086, I've fixed some bugs in the doxygen-generated documentation.

Pull Request resolved: facebookresearch#3092

Reviewed By: pemazare

Differential Revision: D50595811

Pulled By: mdouze

fbshipit-source-id: 74797d3f2594a20597e1eb6545e91f6eac6d035d

Author: epishchik

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(

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<float> cached_l2norms;
 
+    /**
+     * @param d dimensionality of the input vectors
+     */
     explicit IndexFlatL2(idx_t d) : IndexFlat(d, METRIC_L2) {}
     IndexFlatL2() {}
 

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;

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();