add comments about any kwargs

Author: lev-blit

stubs/Pygments/pygments/filter.pyi

@@ -10,11 +10,13 @@ def apply_filters(
 def simplefilter(f: Callable[..., Any]) -> type[FunctionFilter]: ...
 
 class Filter:
-    options: Any
+    options: dict[str, Any]
+    # options are kept as a dict on the instance
     def __init__(self, **options: Any) -> None: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...
 
 class FunctionFilter(Filter):
     function: Callable[..., Any] | None = None
+    # options are forwarded to Filter's constructor
     def __init__(self, **options: Any) -> None: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...

stubs/Pygments/pygments/filters/__init__.pyi

@@ -13,6 +13,7 @@ def get_all_filters() -> Generator[str, None, None]: ...
 
 class CodeTagFilter(Filter):
     tag_re: Any
+    # options are forwarded to Filter's constructor
     def __init__(self, **options: Any) -> None: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...
 
@@ -21,39 +22,46 @@ class SymbolFilter(Filter):
     isabelle_symbols: dict[str, str]
     lang_map: dict[str, dict[str, str]]
     symbols: dict[str, str]
+    # options are forwarded to Filter's constructor
     def __init__(self, **options: Any) -> None: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...
 
 class KeywordCaseFilter(Filter):
     convert: Callable[[str], str]
+    # options are forwarded to Filter's constructor
     def __init__(self, **options: Any) -> None: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...
 
 class NameHighlightFilter(Filter):
     names: set[str]
     tokentype: _TokenType
+    # options are forwarded to Filter's constructor
     def __init__(self, **options: Any) -> None: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...
 
 class ErrorToken(Exception): ...
 
 class RaiseOnErrorTokenFilter(Filter):
     exception: type[Exception]
+    # options are forwarded to Filter's constructor
     def __init__(self, **options: Any) -> None: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...
 
 class VisibleWhitespaceFilter(Filter):
     wstt: bool
+    # options are forwarded to Filter's constructor
     def __init__(self, **options: Any) -> None: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...
 
 class GobbleFilter(Filter):
     n: int
+    # options are forwarded to Filter's constructor
     def __init__(self, **options: Any) -> None: ...
     def gobble(self, value: str, left: int) -> tuple[str, int]: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...
 
 class TokenMergeFilter(Filter):
+    # options are forwarded to Filter's constructor
     def __init__(self, **options: Any) -> None: ...
     def filter(self, lexer: Lexer, stream: Iterable[tuple[_TokenType, str]]) -> Iterator[tuple[_TokenType, str]]: ...
 

stubs/Pygments/pygments/formatter.pyi

@@ -24,6 +24,7 @@ class Formatter(Generic[_T]):
     def __init__(self: Formatter[str], *, encoding: None = None, outencoding: None = None, **options: Any) -> None: ...
     @overload
     def __init__(self: Formatter[bytes], *, encoding: str, outencoding: None = None, **options: Any) -> None: ...
+    # options are kept as a dict on the instance, some are used directly in the constructor
     @overload
     def __init__(self: Formatter[bytes], *, encoding: None = None, outencoding: str, **options: Any) -> None: ...
     def get_style_defs(self, arg: str = "") -> str: ...

stubs/Pygments/pygments/formatters/__init__.pyi

@@ -21,6 +21,12 @@ from .terminal256 import Terminal256Formatter as Terminal256Formatter, TerminalT
 
 def get_all_formatters() -> Generator[type[Formatter[Any]], None, None]: ...
 def find_formatter_class(alias: str) -> type[Formatter[Any]]: ...
+
+# options are forwarded to the formatter's constructor
 def get_formatter_by_name(_alias: str, **options: Any) -> Formatter[Any]: ...
+
+# options are forwarded to the formatter's constructor
 def load_formatter_from_file(filename: str, formattername: str = "CustomFormatter", **options: Any) -> Formatter[Any]: ...
+
+# options are forwarded to the formatter's constructor
 def get_formatter_for_filename(fn: str, **options: Any) -> Formatter[Any]: ...

stubs/Pygments/pygments/lexer.pyi

@@ -47,7 +47,9 @@ class Lexer(metaclass=LexerMeta):
     tabsize: int
     encoding: str
     filters: list[Filter]
+    # options are kept as a dict on the instance
     def __init__(self, **options: Any) -> None: ...
+    # options are forwarded to the filter's constructor
     def add_filter(self, filter_: str | Filter, **options: Any) -> None: ...
     def get_tokens(self, text: str, unfiltered: bool = False) -> Iterator[tuple[_TokenType, str]]: ...
     def get_tokens_unprocessed(self, text: str) -> Iterator[tuple[int, _TokenType, str]]: ...
@@ -56,6 +58,7 @@ class DelegatingLexer(Lexer):
     root_lexer: Lexer
     language_lexer: Lexer
     needle: Incomplete
+    # options are forwarded to the lexer's constructor
     def __init__(
         self, _root_lexer: type[Lexer], _language_lexer: type[Lexer], _needle: _TokenType = ..., **options: Any
     ) -> None: ...
@@ -86,6 +89,7 @@ class _This: ...
 
 this: _This
 
+# kwargs are forwarded to the lexer's constructor
 def using(
     _other: _This | Lexer, **kwargs: Any
 ) -> Callable[[Lexer, _PseudoMatch, LexerContext], Iterator[tuple[int, _TokenType, str]]]: ...
@@ -125,6 +129,7 @@ class RegexLexerMeta(LexerMeta):
             | tuple[str, _TokenType | Iterator[tuple[int, _TokenType, str]], str]
         ],
     ]: ...
+    # kwds are forwarded to `type.__call__`
     def __call__(cls, *args: Any, **kwds: Any) -> Any: ...
 
 _TokenListSecondItemType: TypeAlias = (