BVhhdZddlmZmZedZdZdedefdZdZd Zdee fd Z eZ e Z d Z dedefd Zd ZdedefdZdZdedefdZeZdZdedefdZdZdedefdZy)z!Documentation control decorators.)OptionalTypeVarT_tf_docs_deprecatedobjreturnc(t|td|S)z=Explicitly tag an object as deprecated for the doc generator.N)setattr _DEPRECATEDrs R/home/dcms/DCMS/lib/python3.12/site-packages/tensorflow/tools/docs/doc_controls.pyset_deprecatedrs #{D! *_tf_docs_inheritable_headercfd}|S)Nc*t|t|SN)r _INHERITABLE_HEADER)clstexts r _wrappedz$inheritable_header.._wrapped$s C$d+ Jr)rrs` r inheritable_headerr"s /rc$t|tdSr)getattrrr s r get_inheritable_headerr+s )4 00r_tf_docs_do_not_documentc(t|td|S)aA decorator: Do not generate docs for this object. For example the following classes: ``` class Parent(object): def method1(self): pass def method2(self): pass class Child(Parent): def method1(self): pass def method2(self): pass ``` Produce the following api_docs: ``` /Parent.md # method1 # method2 /Child.md # method1 # method2 ``` This decorator allows you to skip classes or methods: ``` @do_not_generate_docs class Parent(object): def method1(self): pass def method2(self): pass class Child(Parent): @do_not_generate_docs def method1(self): pass def method2(self): pass ``` This will only produce the following docs: ``` /Child.md # method2 ``` Note: This is implemented by adding a hidden attribute on the object, so it cannot be used on objects which do not allow new attributes to be added. So this decorator must go *below* `@property`, `@classmethod`, or `@staticmethod`: ``` class Example(object): @property @do_not_generate_docs def x(self): return self._x ``` Args: obj: The object to hide from the generated docs. Returns: obj N)r _DO_NOT_DOCr s r do_not_generate_docsr 5sT #{D! *r_tf_docs_do_not_doc_inheritablec(t|td|S)aA decorator: Do not generate docs for this method. This version of the decorator is "inherited" by subclasses. No docs will be generated for the decorated method in any subclass. Even if the sub-class overrides the method. For example, to ensure that `method1` is **never documented** use this decorator on the base-class: ``` class Parent(object): @do_not_doc_inheritable def method1(self): pass def method2(self): pass class Child(Parent): def method1(self): pass def method2(self): pass ``` This will produce the following docs: ``` /Parent.md # method2 /Child.md # method2 ``` When generating docs for a class's arributes, the `__mro__` is searched and the attribute will be skipped if this decorator is detected on the attribute on any class in the `__mro__`. Note: This is implemented by adding a hidden attribute on the object, so it cannot be used on objects which do not allow new attributes to be added. So this decorator must go *below* `@property`, `@classmethod`, or `@staticmethod`: ``` class Example(object): @property @do_not_doc_inheritable def x(self): return self._x ``` Args: obj: The class-attribute to hide from the generated docs. Returns: obj N)r _DO_NOT_DOC_INHERITABLEr s r do_not_doc_inheritabler$sp #&- *r(_tf_docs_tools_for_subclass_implementersc(t|td|S)a6A decorator: Only generate docs for this method in the defining class. Also group this method's docs with and `@abstractmethod` in the class's docs. No docs will generated for this class attribute in sub-classes. The canonical use case for this is `tf.keras.layers.Layer.call`: It's a public method, essential for anyone implementing a subclass, but it should never be called directly. Works on method, or other class-attributes. When generating docs for a class's arributes, the `__mro__` is searched and the attribute will be skipped if this decorator is detected on the attribute on any **parent** class in the `__mro__`. For example: ``` class Parent(object): @for_subclass_implementers def method1(self): pass def method2(self): pass class Child1(Parent): def method1(self): pass def method2(self): pass class Child2(Parent): def method1(self): pass def method2(self): pass ``` This will produce the following docs: ``` /Parent.md # method1 # method2 /Child1.md # method2 /Child2.md # method2 ``` Note: This is implemented by adding a hidden attribute on the object, so it cannot be used on objects which do not allow new attributes to be added. So this decorator must go *below* `@property`, `@classmethod`, or `@staticmethod`: ``` class Example(object): @property @for_subclass_implementers def x(self): return self._x ``` Args: obj: The class-attribute to hide from the generated docs. Returns: obj N)r _FOR_SUBCLASS_IMPLEMENTERSr s r for_subclass_implementersr(sN #)40 *r_tf_docs_doc_privatec(t|td|S)aA decorator: Generates docs for private methods/functions. For example: ``` class Try: @doc_controls.doc_private def _private(self): ... ``` As a rule of thumb, private(beginning with `_`) methods/functions are not documented. This decorator allows to force document a private method/function. Args: obj: The class-attribute to hide from the generated docs. Returns: obj N)r _DOC_PRIVATEr s r doc_privater,s2 #|T" *r&_tf_docs_doc_in_current_and_subclassesc(t|td|S)aOverrides `do_not_doc_in_subclasses` decorator. If this decorator is set on a child class's method whose parent's method contains `do_not_doc_in_subclasses`, then that will be overriden and the child method will get documented. All classes inherting from the child will also document that method. For example: ``` class Parent: @do_not_doc_in_subclasses def method1(self): pass def method2(self): pass class Child1(Parent): @doc_in_current_and_subclasses def method1(self): pass def method2(self): pass class Child2(Parent): def method1(self): pass def method2(self): pass class Child11(Child1): pass ``` This will produce the following docs: ``` /Parent.md # method1 # method2 /Child1.md # method1 # method2 /Child2.md # method2 /Child11.md # method1 # method2 ``` Args: obj: The class-attribute to hide from the generated docs. Returns: obj N)r _DOC_IN_CURRENT_AND_SUBCLASSESr s r doc_in_current_and_subclassesr05st #-t4 *rN)__doc__typingrrrr rrrstrrheader get_headerrr r#r$r'r(do_not_doc_in_subclassesr+r,r/r0rrr r7s($ CL$   a 418C=1  # ( K aK AK \<9 9 a9 xHH 1H H V5%  Q 1 :"J; q; Q; r