Improve misc and extra filter doc comments

liquid/builtin/filters/array.py

@@ -80,7 +80,7 @@ def join(
     *,
     environment: Environment,
 ) -> str:
-    """Return a string of items in _sequence_ separated by _separator_."""
+    """Return a string by joining items in _sequence_, separated by _separator_."""
     if not isinstance(separator, str):
         separator = str(separator)
 
@@ -107,7 +107,7 @@ def first(obj: Any) -> object:
 
 @liquid_filter
 def last(obj: Sequence[Any]) -> object:
-    """Return the last item of collection _obj_."""
+    """Return the last item of array-like object _obj_."""
     if isinstance(obj, str):
         return None
 

liquid/builtin/filters/extra.py

@@ -18,7 +18,7 @@
 @with_environment
 @string_filter
 def safe(val: str, *, environment: Environment) -> str:
-    """Stringify and mark as safe."""
+    """Return a copy of _val_ that will not be automatically HTML escaped on output."""
     if environment.autoescape:
         return Markup(val)
     return val

liquid/builtin/filters/misc.py

@@ -27,7 +27,10 @@
 
 @liquid_filter
 def size(obj: Any) -> int:
-    """Return the length of an array or string."""
+    """Return the length of _obj_.
+
+    _obj_ could be a dict, list, string or any class implementing _len_.
+    """
     try:
         return len(obj)
     except TypeError:
@@ -36,7 +39,7 @@ def size(obj: Any) -> int:
 
 @liquid_filter
 def default(obj: Any, default_: object = "", *, allow_false: bool = False) -> Any:
-    """Return a default value if the input is nil, false, or empty."""
+    """Return _obj_, or _default_ if _obj_ is nil, false, or empty."""
     _obj = obj
 
     # Return the default value immediately if the object defines a
@@ -69,7 +72,7 @@ def date(  # noqa: PLR0912 PLR0911
     *,
     environment: Environment,
 ) -> str:
-    """Format a datetime according the the given format string."""
+    """Return a string representation of _dat_ using format string _fmt_."""
     if is_undefined(dat):
         return ""