Documentation
Documentation Container.
The documentation container unifies and eases the handling of documentation strings. Especially doc_from_type() serves the standard approach, to create doc for a type related instance.
Bases: LightObject
Documentation Container.
Documentation is always about a title, a long description and an optional source code comment. Doc carries all 3 of them.
Attributes:
| Name | Type | Description |
|---|---|---|
title |
str | None
|
Full Spoken Name. |
descr |
str | None
|
Documentation Description. |
comment |
str | None
|
Source Code Comment. Default is 'title' |
Dictorary Examples
Basics:
>>> from tabulate import tabulate
>>> import ucdp as u
>>> docs = (
... u.Doc(),
... u.Doc(title='title'),
... u.Doc(title='title', comment=None),
... u.Doc(descr='descr'),
... u.Doc(comment='comment')
... )
>>> print(tabulate([(doc, doc.title, doc.descr, doc.comment, doc.comment_or_title) for doc in docs],
... headers=("Doc()", ".title", ".descr", ".comment", ".comment_or_title")))
Doc() .title .descr .comment .comment_or_title
---------------------- -------- -------- ---------- -------------------
Doc()
Doc(title='title') title title
Doc(title='title') title title
Doc(descr='descr') descr
Doc(comment='comment') comment comment
Documentation instances are singleton and share the same memory:
>>> Doc(title='title') is Doc(title='title')
True
class-attribute
instance-attribute
Full Spoken Name.
Identifier are often appreviations.
The title should contain the full spoken name.
A signal amp_gain should have the title Amplifier Gain.
class-attribute
instance-attribute
Documentation Description.
The descr can contain any multiline user documentation.
class-attribute
instance-attribute
Source Code Comment.
Source code should be commented.
The comment can contain any developer / non-user documentation.
Anything useful developer information.