Merge pull request diffblue#4392 from tautschnig/fix-byte-op-lowering-docs

Fix lower_byte_{extract,update}'s documentation

Author: smowton

src/solvers/lowering/expr_lowering.h

@@ -19,15 +19,19 @@ class popcount_exprt;
 /// Rewrite a byte extract expression to more fundamental operations.
 /// \param src: Byte extract expression
 /// \param ns: Namespace
-/// \return Semantically equivalent expression that does not contain any \ref
-///   byte_extract_exprt or \ref byte_update_exprt.
+/// \return Semantically equivalent expression such that the top-level
+///   expression no longer is a \ref byte_extract_exprt or
+///   \ref byte_update_exprt. Use \ref lower_byte_operators to also remove all
+///   byte operators from any operands of \p src.
 exprt lower_byte_extract(const byte_extract_exprt &src, const namespacet &ns);
 
 /// Rewrite a byte update expression to more fundamental operations.
 /// \param src: Byte update expression
 /// \param ns: Namespace
-/// \return Semantically equivalent expression that does not contain any \ref
-///   byte_extract_exprt or \ref byte_update_exprt.
+/// \return Semantically equivalent expression such that the top-level
+///   expression no longer is a \ref byte_extract_exprt or
+///   \ref byte_update_exprt. Use \ref lower_byte_operators to also remove all
+///   byte operators from any operands of \p src.
 exprt lower_byte_update(const byte_update_exprt &src, const namespacet &ns);
 
 /// Rewrite an expression possibly containing byte-extract or -update