doc: document that hs_close_stream frees memory

Add explicit documentation that hs_close_stream() will free the stream
state after returning any matches.

src/hs_common.h

@@ -479,6 +479,10 @@ hs_error_t HS_CDECL hs_valid_platform(void);
 
 /**
  * A parameter passed to this function was invalid.
+ *
+ * This error is only returned in cases where the function can detect an
+ * invalid parameter -- it cannot be relied upon to detect (for example)
+ * pointers to freed memory or other invalid data.
  */
 #define HS_INVALID              (-1)