diff --git a/ql/instruments/swaption.hpp b/ql/instruments/swaption.hpp
index b3353e42bab..5d6c1cdf3cf 100644
--- a/ql/instruments/swaption.hpp
+++ b/ql/instruments/swaption.hpp
@@ -59,6 +59,12 @@ namespace QuantLib {
     //! %Swaption class
     /*! \ingroup instruments
 
+        \warning it's possible to pass an overnight-indexed swap to
+                 the constructor, but the only engine to fully support
+                 it is BlackSwaptionEngine; other engines will treat
+                 it as a vanilla swap.  This is at best a decent
+                 proxy, at worst simply wrong.  Use with caution.
+
         \test
         - the correctness of the returned value is tested by checking
           that the price of a payer (resp. receiver) swaption
diff --git a/ql/models/shortrate/calibrationhelpers/swaptionhelper.hpp b/ql/models/shortrate/calibrationhelpers/swaptionhelper.hpp
index e8c6ac90046..a5a4f9a81fe 100644
--- a/ql/models/shortrate/calibrationhelpers/swaptionhelper.hpp
+++ b/ql/models/shortrate/calibrationhelpers/swaptionhelper.hpp
@@ -32,8 +32,13 @@
 
 namespace QuantLib {
 
-    //! calibration helper for ATM swaption
-
+    //! calibration helper for interest-rate swaptions
+    /*! \warning passing an overnight index to the constructor will
+                 result in an overnight-indexed swap being built, but
+                 model-based engines will treat it as a vanilla swap.
+                 This is at best a decent proxy, at worst simply wrong.
+                 Use with caution.
+    */
     class SwaptionHelper : public BlackCalibrationHelper {
       public:
         SwaptionHelper(const Period& maturity,