Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/tensorflow/tools/docs/doc_controls.py: 66%

1# Copyright 2018 The TensorFlow Authors. All Rights Reserved. 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14# ============================================================================== 

15"""Documentation control decorators.""" 

16 

17from typing import Optional, TypeVar 

18 

19T = TypeVar("T") 

20 

21 

22_DEPRECATED = "_tf_docs_deprecated" 

23 

24 

25def set_deprecated(obj: T) -> T: 

26 """Explicitly tag an object as deprecated for the doc generator.""" 

27 setattr(obj, _DEPRECATED, None) 

28 return obj 

29 

30 

31_INHERITABLE_HEADER = "_tf_docs_inheritable_header" 

32 

33 

34def inheritable_header(text): 

35 

36 def _wrapped(cls): 

37 setattr(cls, _INHERITABLE_HEADER, text) 

38 return cls 

39 

40 return _wrapped 

41 

42 

43def get_inheritable_header(obj) -> Optional[str]: 

44 return getattr(obj, _INHERITABLE_HEADER, None) 

45 

46 

47header = inheritable_header 

48get_header = get_inheritable_header 

49 

50_DO_NOT_DOC = "_tf_docs_do_not_document" 

51 

52 

53def do_not_generate_docs(obj: T) -> T: 

54 """A decorator: Do not generate docs for this object. 

55 

56 For example the following classes: 

57 

58 ``` 

59 class Parent(object): 

60 def method1(self): 

61 pass 

62 def method2(self): 

63 pass 

64 

65 class Child(Parent): 

66 def method1(self): 

67 pass 

68 def method2(self): 

69 pass 

70 ``` 

71 

72 Produce the following api_docs: 

73 

74 ``` 

75 /Parent.md 

76 # method1 

77 # method2 

78 /Child.md 

79 # method1 

80 # method2 

81 ``` 

82 

83 This decorator allows you to skip classes or methods: 

84 

85 ``` 

86 @do_not_generate_docs 

87 class Parent(object): 

88 def method1(self): 

89 pass 

90 def method2(self): 

91 pass 

92 

93 class Child(Parent): 

94 @do_not_generate_docs 

95 def method1(self): 

96 pass 

97 def method2(self): 

98 pass 

99 ``` 

100 

101 This will only produce the following docs: 

102 

103 ``` 

104 /Child.md 

105 # method2 

106 ``` 

107 

108 Note: This is implemented by adding a hidden attribute on the object, so it 

109 cannot be used on objects which do not allow new attributes to be added. So 

110 this decorator must go *below* `@property`, `@classmethod`, 

111 or `@staticmethod`: 

112 

113 ``` 

114 class Example(object): 

115 @property 

116 @do_not_generate_docs 

117 def x(self): 

118 return self._x 

119 ``` 

120 

121 Args: 

122 obj: The object to hide from the generated docs. 

123 

124 Returns: 

125 obj 

126 """ 

127 setattr(obj, _DO_NOT_DOC, None) 

128 return obj 

129 

130 

131_DO_NOT_DOC_INHERITABLE = "_tf_docs_do_not_doc_inheritable" 

132 

133 

134def do_not_doc_inheritable(obj: T) -> T: 

135 """A decorator: Do not generate docs for this method. 

136 

137 This version of the decorator is "inherited" by subclasses. No docs will be 

138 generated for the decorated method in any subclass. Even if the sub-class 

139 overrides the method. 

140 

141 For example, to ensure that `method1` is **never documented** use this 

142 decorator on the base-class: 

143 

144 ``` 

145 class Parent(object): 

146 @do_not_doc_inheritable 

147 def method1(self): 

148 pass 

149 def method2(self): 

150 pass 

151 

152 class Child(Parent): 

153 def method1(self): 

154 pass 

155 def method2(self): 

156 pass 

157 ``` 

158 This will produce the following docs: 

159 

160 ``` 

161 /Parent.md 

162 # method2 

163 /Child.md 

164 # method2 

165 ``` 

166 

167 When generating docs for a class's arributes, the `__mro__` is searched and 

168 the attribute will be skipped if this decorator is detected on the attribute 

169 on any class in the `__mro__`. 

170 

171 Note: This is implemented by adding a hidden attribute on the object, so it 

172 cannot be used on objects which do not allow new attributes to be added. So 

173 this decorator must go *below* `@property`, `@classmethod`, 

174 or `@staticmethod`: 

175 

176 ``` 

177 class Example(object): 

178 @property 

179 @do_not_doc_inheritable 

180 def x(self): 

181 return self._x 

182 ``` 

183 

184 Args: 

185 obj: The class-attribute to hide from the generated docs. 

186 

187 Returns: 

188 obj 

189 """ 

190 setattr(obj, _DO_NOT_DOC_INHERITABLE, None) 

191 return obj 

192 

193 

194_FOR_SUBCLASS_IMPLEMENTERS = "_tf_docs_tools_for_subclass_implementers" 

195 

196 

197def for_subclass_implementers(obj: T) -> T: 

198 """A decorator: Only generate docs for this method in the defining class. 

199 

200 Also group this method's docs with and `@abstractmethod` in the class's docs. 

201 

202 No docs will generated for this class attribute in sub-classes. 

203 

204 The canonical use case for this is `tf.keras.layers.Layer.call`: It's a 

205 public method, essential for anyone implementing a subclass, but it should 

206 never be called directly. 

207 

208 Works on method, or other class-attributes. 

209 

210 When generating docs for a class's arributes, the `__mro__` is searched and 

211 the attribute will be skipped if this decorator is detected on the attribute 

212 on any **parent** class in the `__mro__`. 

213 

214 For example: 

215 

216 ``` 

217 class Parent(object): 

218 @for_subclass_implementers 

219 def method1(self): 

220 pass 

221 def method2(self): 

222 pass 

223 

224 class Child1(Parent): 

225 def method1(self): 

226 pass 

227 def method2(self): 

228 pass 

229 

230 class Child2(Parent): 

231 def method1(self): 

232 pass 

233 def method2(self): 

234 pass 

235 ``` 

236 

237 This will produce the following docs: 

238 

239 ``` 

240 /Parent.md 

241 # method1 

242 # method2 

243 /Child1.md 

244 # method2 

245 /Child2.md 

246 # method2 

247 ``` 

248 

249 Note: This is implemented by adding a hidden attribute on the object, so it 

250 cannot be used on objects which do not allow new attributes to be added. So 

251 this decorator must go *below* `@property`, `@classmethod`, 

252 or `@staticmethod`: 

253 

254 ``` 

255 class Example(object): 

256 @property 

257 @for_subclass_implementers 

258 def x(self): 

259 return self._x 

260 ``` 

261 

262 Args: 

263 obj: The class-attribute to hide from the generated docs. 

264 

265 Returns: 

266 obj 

267 """ 

268 setattr(obj, _FOR_SUBCLASS_IMPLEMENTERS, None) 

269 return obj 

270 

271 

272do_not_doc_in_subclasses = for_subclass_implementers 

273 

274_DOC_PRIVATE = "_tf_docs_doc_private" 

275 

276 

277def doc_private(obj: T) -> T: 

278 """A decorator: Generates docs for private methods/functions. 

279 

280 For example: 

281 

282 ``` 

283 class Try: 

284 

285 @doc_controls.doc_private 

286 def _private(self): 

287 ... 

288 ``` 

289 

290 As a rule of thumb, private(beginning with `_`) methods/functions are 

291 not documented. 

292 

293 This decorator allows to force document a private method/function. 

294 

295 Args: 

296 obj: The class-attribute to hide from the generated docs. 

297 

298 Returns: 

299 obj 

300 """ 

301 

302 setattr(obj, _DOC_PRIVATE, None) 

303 return obj 

304 

305 

306_DOC_IN_CURRENT_AND_SUBCLASSES = "_tf_docs_doc_in_current_and_subclasses" 

307 

308 

309def doc_in_current_and_subclasses(obj: T) -> T: 

310 """Overrides `do_not_doc_in_subclasses` decorator. 

311 

312 If this decorator is set on a child class's method whose parent's method 

313 contains `do_not_doc_in_subclasses`, then that will be overriden and the 

314 child method will get documented. All classes inherting from the child will 

315 also document that method. 

316 

317 For example: 

318 

319 ``` 

320 class Parent: 

321 @do_not_doc_in_subclasses 

322 def method1(self): 

323 pass 

324 def method2(self): 

325 pass 

326 

327 class Child1(Parent): 

328 @doc_in_current_and_subclasses 

329 def method1(self): 

330 pass 

331 def method2(self): 

332 pass 

333 

334 class Child2(Parent): 

335 def method1(self): 

336 pass 

337 def method2(self): 

338 pass 

339 

340 class Child11(Child1): 

341 pass 

342 ``` 

343 

344 This will produce the following docs: 

345 

346 ``` 

347 /Parent.md 

348 # method1 

349 # method2 

350 /Child1.md 

351 # method1 

352 # method2 

353 /Child2.md 

354 # method2 

355 /Child11.md 

356 # method1 

357 # method2 

358 ``` 

359 

360 Args: 

361 obj: The class-attribute to hide from the generated docs. 

362 

363 Returns: 

364 obj 

365 """ 

366 

367 setattr(obj, _DOC_IN_CURRENT_AND_SUBCLASSES, None) 

368 return obj