docs: Better docstring and warning for C14NWriterTarget

Author: abelcheung

src/lxml-stubs/etree/_serializer.pyi

@@ -38,25 +38,109 @@ else:
 
 class SerialisationError(LxmlError): ...
 
-# Interface quite similar to a ParserTarget, but canonicalized output
+# Usage identical to custom target parser, but canonicalized output
 # is written during various stages before calling .close()
 class C14NWriterTarget:
+    """Canonicalization writer target for the XMLParser. Serialises parse events
+    to XML C14N 2.0.
+
+    Annotation
+    ----------
+    Totally 5 overload signatures. The first 4 deal with erroneous usage of
+    tag or attribute parameters, and final one covers normal usage.
+
+    See Also
+    --------
+    - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.C14NWriterTarget)
+    """
     @overload
-    @deprecated("Should specify a collection or iterator of tags")
-    def __init__(self, *args: Any, qname_aware_tags: str, **kw: Any) -> Never: ...
+    @deprecated(
+        "'qname_aware_tags' should be iterable of tags, "
+        "otherwise it will silently fail to replace any tag"
+    )
+    def __init__(
+        self, write: Callable[[str], object], *, qname_aware_tags: str, **kw: Any
+    ) -> Never:
+        """Canonicalization writer target for the XMLParser. Serialises parse
+        events to XML C14N 2.0.
+
+        Annotation
+        ----------
+        This overload signature handles the case where `exclude_tags` parameter
+        is wrongly specified as a plain `str`. It will be broken down into
+        characters and each character will be treated as a single tag.
+
+        See Also
+        --------
+        - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.C14NWriterTarget)
+        """
     @overload
-    @deprecated("Should specify a collection or iterator of attributes")
-    def __init__(self, *args: Any, qname_aware_attrs: str, **kw: Any) -> Never: ...
+    @deprecated(
+        "'qname_aware_attrs' should be iterable of attributes, "
+        "otherwise it will silently fail to replace any attribute"
+    )
+    def __init__(
+        self, write: Callable[[str], object], *, qname_aware_attrs: str, **kw: Any
+    ) -> Never:
+        """Canonicalization writer target for the XMLParser. Serialises parse
+        events to XML C14N 2.0.
+
+        Annotation
+        ----------
+        This overload signature handles the case where `exclude_attrs` parameter
+        is wrongly specified as a plain `str`. It will be broken down into
+        characters and each character will be treated as a single attribute.
+
+        See Also
+        --------
+        - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.C14NWriterTarget)
+        """
     @overload
-    @deprecated("Should specify a collection or iterator of attributes")
-    def __init__(self, *args: Any, exclude_attrs: str, **kw: Any) -> Never: ...
+    @deprecated(
+        "'exclude_attrs' should be iterable of attributes, "
+        "otherwise it will silently fail to exclude anything"
+    )
+    def __init__(
+        self, write: Callable[[str], object], *, exclude_attrs: str, **kw: Any
+    ) -> Never:
+        """Canonicalization writer target for the XMLParser. Serialises parse
+        events to XML C14N 2.0.
+
+        Annotation
+        ----------
+        This overload signature handles the case where `exclude_attrs` parameter
+        is wrongly specified as a plain `str`. It will be broken down into
+        characters and each character will be treated as a single attribute.
+
+        See Also
+        --------
+        - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.C14NWriterTarget)
+        """
     @overload
-    @deprecated("Should specify a collection or iterator of tags")
-    def __init__(self, *args: Any, exclude_tags: str, **kw: Any) -> Never: ...
+    @deprecated(
+        "'exclude_tags' should be iterable of tags, "
+        "otherwise it will silently fail to exclude anything"
+    )
+    def __init__(
+        self, write: Callable[[str], object], *, exclude_tags: str, **kw: Any
+    ) -> Never:
+        """Canonicalization writer target for the XMLParser. Serialises parse
+        events to XML C14N 2.0.
+
+        Annotation
+        ----------
+        This overload signature handles the case where `exclude_tags` parameter
+        is wrongly specified as a plain `str`. It will be broken down into
+        characters and each character will be treated as a single tag.
+
+        See Also
+        --------
+        - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.C14NWriterTarget)
+        """
     @overload
     def __init__(
         self,
-        write: Callable[[str], Any],
+        write: Callable[[str], object],
         *,
         with_comments: bool = False,
         strip_text: bool = False,
@@ -65,7 +149,19 @@ class C14NWriterTarget:
         qname_aware_attrs: Iterable[str] | None = None,
         exclude_attrs: Iterable[str] | None = None,
         exclude_tags: Iterable[str] | None = None,
-    ) -> None: ...
+    ) -> None:
+        """Canonicalization writer target for the XMLParser. Serialises parse
+        events to XML C14N 2.0.
+
+        Annotation
+        ----------
+        Totally 5 overload signatures. The first 4 deal with erroneous usage of
+        tag or attribute parameters, and final one covers normal usage.
+
+        See Also
+        --------
+        - [API Documentation](https://lxml.de/apidoc/lxml.etree.html#lxml.etree.C14NWriterTarget)
+        """
     def data(self, data: str) -> None: ...
     def start_ns(self, prefix: str, uri: str) -> None: ...
     def start(self, tag: str, attrs: SupportsLaxItems[str, str] | None) -> None: ...