general: Improve documentation

fadec-enc.h

@@ -22,16 +22,26 @@ typedef enum {
 
 typedef int64_t FeOp;
 
+/** Construct a memory operand. Unused parts can be set to 0 and will be
+ * ignored. FE_IP can be used as base register, in which case the offset is
+ * interpreted as the offset from the /current/ position -- the size of the
+ * encoded instruction will be subtracted during encoding. scale must be 1, 2,
+ * 4, or 8; but is ignored if  idx == 0. **/
 #define FE_MEM(base,sc,idx,off) (INT64_MIN | ((int64_t) ((base) & 0xfff) << 32) | ((int64_t) ((idx) & 0xfff) << 44) | ((int64_t) ((sc) & 0xf) << 56) | ((off) & 0xffffffff))
 
+/** Add segment override prefix. This may or may not generate prefixes for the
+ * ignored prefixes ES/CS/DS/SS in 64-bit mode. **/
 #define FE_SEG(seg) ((((seg) & 0x7) + 1) << 16)
+/** Do not use. **/
 #define FE_SEG_MASK 0x70000
+/** Overrides address size. **/
 #define FE_ADDR32 0x80000
 /** Used together with a RIP-relative (conditional) jump, this will force the
  * use of the encoding with the largest distance. Useful for reserving a jump
  * when the target offset is still unknown; if the jump is re-encoded later on,
  * FE_JMPL must be specified there, too, so that the encoding lengths match. **/
 #define FE_JMPL 0x100000
+/** Do not use. **/
 #define FE_MNEM_MASK 0xffff
 
 enum {
@@ -41,8 +51,22 @@ enum {
     FE_MNEM_MAX
 };
 
+/** Do not use. **/
 #define fe_enc64_1(buf, mnem, op0, op1, op2, op3, ...) fe_enc64_impl(buf, mnem, op0, op1, op2, op3)
+/** Encode a single instruction for 64-bit mode.
+ * \param buf Pointer to the buffer for instruction bytes, must have a size of
+ *        15 bytes. The pointer is advanced by the number of bytes used for
+ *        encoding the specified instruction.
+ * \param mnem Mnemonic, optionally or-ed with FE_SEG(), FE_ADDR32, or FE_JMPL.
+ * \param operands... Instruction operands. Immediate operands are passed as
+ *        plain value; register operands using the FeReg enum; memory operands
+ *        using FE_MEM(); and offset operands for RIP-relative jumps/calls are
+ *        specified as _address in buf_, e.g. (intptr_t) jmptgt, the address of
+ *        buf and the size of the encoded instruction are subtracted internally.
+ * \return Zero for success or a negative value in case of an error.
+ **/
 #define fe_enc64(buf, ...) fe_enc64_1(buf, __VA_ARGS__, 0, 0, 0, 0, 0)
+/** Do not use. **/
 int fe_enc64_impl(uint8_t** buf, uint64_t mnem, FeOp op0, FeOp op1, FeOp op2, FeOp op3);
 
 #ifdef __cplusplus