| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180 |
- .kind:: example_kind
- ..d: A kind specifying some example attributes and methods.
- .c: This is a comment on the outer level. The comment extends to the
- next line beginning with a dot.
- We have left the scope of example_kind for now.
- The superkinds below are used for argument specification and provide
- values to the generated tests.
- They are not (necessarily) included in the generated document.
- .superkind:: int+
- ..eg: 1
- .superkind:: string+
- ..eg: 'abc'
- .superkind:: list+
- ..eg: []
- .kind:: list_of_integers
- ..d: A kind with no formal properties. In this example, I am not
- specifying anything about this kind. It is to be understood from its
- name and context what it means. More specifications can be added later
- as a system description evolves.
- .and: example_kind
- ..c: Here continues the specification of example_kind.
- ..c: It can be split in several parts, the first one must
- ..c: be a .kind, and the others .and.
- ..c: This can be useful to specify recursive kinds.
- ..attr:: a_nokind
- ...d: An attribute named a_nokind, with unspecified kind.
- ..method:: m_noargs
- ...d: A method that takes no arguments, and returns an unspecified kind.
- ..method:: m_returns
- ...d: A method which returns objects of kind
- ....ref: .myfile.example_kind
- ....t: again.
- ...returns: example_kind
- ..method:: m_one
- ...d: A method with one argument.
- ...arg: a: int+
- ....d: A positional argument of kind
- .....ref: .myfile.int+
- .....t:. The
- .....ref: .mykind.int+
- .....t: kind is a so called
- .....em: superkind
- .....t: because an API with this specification,
- is expected to accept values according to the specification of
- .....ref: .mykind.int+
- .....t:, but it is allowed to accept other kinds of arguments as well. A
- .....em: compatible
- .....t: new specification could add these alternative kinds of
- arguments as allowed arguments, but it would still have to accept the
- .....ref: .mykind.int+
- .....t: kind of argument.
- ...dwh: Note
- The + in the int+ name is a convention to indicate that it is a
- ....em: superkind
- ....t:.
- ...dwh: Note
- The name of the argument, a, does
- ....em: not
- ....t: mean that it can be specified as a keyword argument with that
- name. It is only when keyword arguments are specifically specified
- that they are actually keyword arguments.
- ..method:: m_opt
- ...d: A method with optional arguments. Square brackets without a
- preceding modifier means that the contents is optional. So in this
- case, either no argument must be given, or if one argument is given it
- is a, or if two arguments are given, it is a and b in that order.
- ...optionals
- ....arg: a: int+
- ....arg: b: string+
- ..method:: m_alt
- ...d: A method with alternative arguments.
- An
- ....sup:
- .....strong: alt:
- ....t: before the bracket is a modifier that means that there is a
- choice of alternatives. The argument is required and should be either
- an int+, string+ or list+.
- ...alt
- ....arg: a: int+
- .....d: Description for an int argument.
- ....arg: a: string+
- .....d: Description for a string argument.
- ....arg: a: list+
- .....d: Description for a list argument.
- ..method:: m_repeat
- ...d: A method with repeated arguments.
- A modifier
- ....sup:
- .....strong: m..n:
- ....t: before the argument, where m and n are integers, means an
- argument that may be repeated at least m times and at most n
- times. Instead of n, * may be specified and means any number of times.
- ...repeat: 0..*
- ....arg: a: int+
- .....d: This argument may be repeated any number of times as long as
- it is of of kind int+.
- ...repeat: 2..4
- ....arg: b: string+
- .....d: The final arguments must be of kind string+ and be repeated 2,
- 3 or 4 times.
- ..method:: m_draw_keywords
- ...d: A method with optional keyword arguments.
- ...d: The modifier
- ....sup
- .....strong: draw:
- ....t: means to 'draw' any combination of arguments from within the
- brackets. Keyword arguments by them self would not be optional, but
- would be mandatory, in the current specification system.
- ...draw
- ....key arg: a : int+
- ....key arg: b : int+
- ....key arg: c : string+
- ..method:: range
- ...d: A method combining different argument specifications.
- ...d: The modifier
- ....sup
- .....strong: seq
- ....t: means arguments that are specified by the
- ....em: sequence
- ....t: of arguments within the following brackets.
- ....p: Create a range of numbers.
- ...alt
- ....arg: stop: int+
- ....seq
- .....arg: start: int+
- ......d: The first value of the range.
- ......default: 0
- Starts with first value.
- .....arg: stop: int+
- ......d: The value just beyond the last value of the range.
- .....optionals
- ......arg: step: int+
- .......d: Positive or negative, steps values up or down.
- .......default: 1
- ...returns: list_of_integers
- ....d: a list containing an arithmetic progression of integers.
- .document: docexample
- ..output: html, tester
- ..man page of: list_of_integers
- ..man page of: example_kind
- ..test of: example_kind
|