diff --git a/include/libtorrent/alert_types.hpp b/include/libtorrent/alert_types.hpp
index 753eb48ea..29ac853ab 100644
--- a/include/libtorrent/alert_types.hpp
+++ b/include/libtorrent/alert_types.hpp
@@ -868,6 +868,9 @@ TORRENT_VERSION_NAMESPACE_2
 	// this alert is posted every time a piece completes downloading
 	// and passes the hash check. This alert derives from torrent_alert
 	// which contains the torrent_handle to the torrent the piece belongs to.
+	// Note that being downloaded and passing the hash check may happen before
+	// the piece is also fully flushed to disk. So torrent_handle::have_piece()
+	// may still return false
 	struct TORRENT_EXPORT piece_finished_alert final : torrent_alert
 	{
 		// internal
diff --git a/include/libtorrent/torrent_handle.hpp b/include/libtorrent/torrent_handle.hpp
index 9af651cbb..92afcf7a3 100644
--- a/include/libtorrent/torrent_handle.hpp
+++ b/include/libtorrent/torrent_handle.hpp
@@ -287,8 +287,8 @@ namespace aux {
 		// guaranteed to finish in the same order as you initiated them.
 		void read_piece(piece_index_t piece) const;
 
-		// Returns true if this piece has been completely downloaded, and false
-		// otherwise.
+		// Returns true if this piece has been completely downloaded and written
+		// to disk, and false otherwise.
 		bool have_piece(piece_index_t piece) const;
 
 #if TORRENT_ABI_VERSION == 1