Docs: update hpsi_func requirements (#5190)

Author: Cstandardlib

source/module_hsolver/diago_david.cpp

@@ -1149,6 +1149,10 @@ void DiagoDavid<T, Device>::planSchmidtOrth(const int nband, std::vector<int>& p
 /**
  * @brief Performs iterative diagonalization using the David algorithm.
  * 
+ * @warning Please see docs of `HPsiFunc` for more information.
+ * @warning Please adhere strictly to the requirements of the function pointer
+ * @warning for the hpsi mat-vec interface; it may seem counterintuitive.
+ * 
  * @tparam T The type of the elements in the matrix.
  * @tparam Device The device type (CPU or GPU).
  * @param hpsi_func The function object that computes the matrix-blockvector product H * psi.

source/module_hsolver/diago_david.h

@@ -36,13 +36,23 @@ class DiagoDavid : public DiagH<T, Device>
      * This function type is used to define a matrix-blockvector operator H.
      * For eigenvalue problem HX = λX or generalized eigenvalue problem HX = λSX,
      * this function computes the product of the Hamiltonian matrix H and a blockvector X.
+     * 
+     * Called as follows:
+     * hpsi(X, HX, nvec, dim, id_start, id_end)
+     * Result is stored in HX.
+     * HX = H * X[id_start:id_end]
      *
-     * @param[out] X      Pointer to input blockvector of type `T*`.
-     * @param[in]  HX     Pointer to output blockvector of type `T*`.
+     * @param[out] X      Head address of input blockvector of type `T*`.
+     * @param[in]  HX     Where to write output blockvector of type `T*`.
      * @param[in]  nvec   Number of eigebpairs, i.e. number of vectors in a block.
      * @param[in]  dim    Dimension of matrix.
      * @param[in]  id_start Start index of blockvector.
      * @param[in]  id_end   End index of blockvector.
+     * 
+     * @warning HX is the exact address to store output H*X[id_start:id_end];
+     * @warning while X is the head address of input blockvector, \b without offset.
+     * @warning Calling function should pass X and HX[offset] as arguments,
+     * @warning where offset is usually id_start * leading dimension.
      */
     using HPsiFunc = std::function<void(T*, T*, const int, const int, const int, const int)>;