Move/adapt docs from DOC.md for condition object

lua/luasnip/extras/conditions/init.lua

@@ -1,5 +1,33 @@
---- A composable condition object, can be used for `condition` in a snippet
---- context.
+
+--- A composable condition object. It can be used for `condition` in a snippet
+--- context but can also be logically combined with other condition
+--- function/object to build complex conditions.
+---
+--- This makes logical combinations of conditions very readable.
+---
+--- Compare
+--- ```lua
+--- local conds = require"luasnip.extras.conditions.expand"
+--- ...
+--- -- using combinator functions:
+--- condition = conds.line_end:or_(conds.line_begin)
+--- -- using operators:
+--- condition = conds.line_end + conds.line_begin
+--- ```
+---
+--- with the more verbose
+---
+--- ```lua
+--- local conds = require"luasnip.extras.conditions.expand"
+--- ...
+--- condition = function(...) return conds.line_end(...) or conds.line_begin(...) end
+--- ```
+---
+--- The conditions provided in `show` and `expand` are already condition objects.
+--- To create new ones, use:
+--- ```lua
+--- require("luasnip.extras.conditions").make_condition(condition_fn)
+--- ```
 ---
 ---@class LuaSnip.SnipContext.ConditionObj
 ---@field func LuaSnip.SnipContext.ConditionFn
@@ -22,8 +50,8 @@ local ConditionObj_mt = {
 	end,
 }
 
---- Wrap the given `condition` function in a composable condition object.
----@param func LuaSnip.SnipContext.Condition
+--- Wrap the given `condition` function into a composable condition object.
+---@param func LuaSnip.SnipContext.ConditionFn
 ---@return LuaSnip.SnipContext.ConditionObj
 function ConditionObj.make_condition(func)
 	return setmetatable({ func = func }, ConditionObj_mt)
@@ -36,7 +64,7 @@ function ConditionObj:inverted()
 		return not self(...)
 	end)
 end
--- (e.g. `-cond`)
+--- (e.g. `-cond`, implemented as `cond:inverted()`)
 ConditionObj_mt.__unm = ConditionObj.inverted
 
 --- Returns a condition object equivalent to `self(...) or other(...)`
@@ -47,18 +75,25 @@ function ConditionObj:or_(other)
 		return self(...) or other(...)
 	end)
 end
--- (e.g. `cond1 + cond2`)
+--- (e.g. `cond1 + cond2`, implemented as `cond1:or_(cond2)`)
 ConditionObj_mt.__add = ConditionObj.or_
 
 --- Returns a condition object equivalent to `self(...) and not other(...)`
+---
+--- This is similar to set differences: `A \ B = {a in A | a not in B}`.
+--- This makes `-(a + b) = -a - b` an identity representing de Morgan's law:
+--- `not (a or b) = not a and not b`.
+--- However, since boolean algebra lacks an additive inverse, `a + (-b) = a - b`
+--- does not hold. Thus, this is NOT the same as `c1 + (-c2)`.
+---
 ---@param other LuaSnip.SnipContext.Condition
 ---@return LuaSnip.SnipContext.ConditionObj
 function ConditionObj:and_not(other)
 	return ConditionObj.make_condition(function(...)
 		return self(...) and not other(...)
 	end)
 end
--- (e.g. `cond1 - cond2`)
+--- (e.g. `cond1 - cond2`, implemented as `cond1:and_not(cond2)`)
 ConditionObj_mt.__sub = ConditionObj.and_not
 
 --- Returns a condition object equivalent to `self(...) and other(...)`
@@ -69,31 +104,35 @@ function ConditionObj:and_(other)
 		return self(...) and other(...)
 	end)
 end
--- (e.g. `cond1 * cond2`)
+--- (e.g. `cond1 * cond2`, implemented as `cond1:and_(cond2)`)
 ConditionObj_mt.__mul = ConditionObj.and_
 
---- Returns a condition object equivalent to `self(...) ~= other(...)`
+--- Returns a condition object equivalent to `self(...) ~= other(...)` (xor)
 ---@param other LuaSnip.SnipContext.Condition
 ---@return LuaSnip.SnipContext.ConditionObj
 function ConditionObj:not_same_as(other)
 	return ConditionObj.make_condition(function(...)
 		return self(...) ~= other(...)
 	end)
 end
--- (e.g. `cond1 ^ cond2`)
+--- (e.g. `cond1 ^ cond2`, implemented as `cond1:not_same_as(cond2)`)
 ConditionObj_mt.__pow = ConditionObj.not_same_as
 
---- Returns a condition object equivalent to `self(...) == other(...)`
+--- Returns a condition object equivalent to `self(...) == other(...)` (xnor)
 ---@param other LuaSnip.SnipContext.Condition
 ---@return LuaSnip.SnipContext.ConditionObj
 function ConditionObj:same_as(other)
 	return ConditionObj.make_condition(function(...)
 		return self(...) == other(...)
 	end)
 end
--- (e.g. `cond1 % cond2`)
--- This operator might be counter intuitive, but '==' can't be used as it must
--- return a boolean. It's best to use something weird (doesn't have to be used)
+--- (e.g. `cond1 % cond2`, implemented as `cond1:same_as(cond2)`)
+---
+--- Using `%` might be counter intuitive, considering the `==`-operator exists,
+--- unfortunately, it's not possible to use this for our purposes (some info
+--- [here](https://github.com/L3MON4D3/LuaSnip/pull/612#issuecomment-1264487743)).
+--- We decided instead to make use of a more obscure symbol (which will
+--- hopefully avoid false assumptions about its meaning).
 ConditionObj_mt.__mod = ConditionObj.same_as
 
 return ConditionObj