docexample.gsl 4.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180
  1. .kind:: example_kind
  2. ..d: A kind specifying some example attributes and methods.
  3. .c: This is a comment on the outer level. The comment extends to the
  4. next line beginning with a dot.
  5. We have left the scope of example_kind for now.
  6. The superkinds below are used for argument specification and provide
  7. values to the generated tests.
  8. They are not (necessarily) included in the generated document.
  9. .superkind:: int+
  10. ..eg: 1
  11. .superkind:: string+
  12. ..eg: 'abc'
  13. .superkind:: list+
  14. ..eg: []
  15. .kind:: list_of_integers
  16. ..d: A kind with no formal properties. In this example, I am not
  17. specifying anything about this kind. It is to be understood from its
  18. name and context what it means. More specifications can be added later
  19. as a system description evolves.
  20. .and: example_kind
  21. ..c: Here continues the specification of example_kind.
  22. ..c: It can be split in several parts, the first one must
  23. ..c: be a .kind, and the others .and.
  24. ..c: This can be useful to specify recursive kinds.
  25. ..attr:: a_nokind
  26. ...d: An attribute named a_nokind, with unspecified kind.
  27. ..method:: m_noargs
  28. ...d: A method that takes no arguments, and returns an unspecified kind.
  29. ..method:: m_returns
  30. ...d: A method which returns objects of kind
  31. ....ref: .myfile.example_kind
  32. ....t: again.
  33. ...returns: example_kind
  34. ..method:: m_one
  35. ...d: A method with one argument.
  36. ...arg: a: int+
  37. ....d: A positional argument of kind
  38. .....ref: .myfile.int+
  39. .....t:. The
  40. .....ref: .mykind.int+
  41. .....t: kind is a so called
  42. .....em: superkind
  43. .....t: because an API with this specification,
  44. is expected to accept values according to the specification of
  45. .....ref: .mykind.int+
  46. .....t:, but it is allowed to accept other kinds of arguments as well. A
  47. .....em: compatible
  48. .....t: new specification could add these alternative kinds of
  49. arguments as allowed arguments, but it would still have to accept the
  50. .....ref: .mykind.int+
  51. .....t: kind of argument.
  52. ...dwh: Note
  53. The + in the int+ name is a convention to indicate that it is a
  54. ....em: superkind
  55. ....t:.
  56. ...dwh: Note
  57. The name of the argument, a, does
  58. ....em: not
  59. ....t: mean that it can be specified as a keyword argument with that
  60. name. It is only when keyword arguments are specifically specified
  61. that they are actually keyword arguments.
  62. ..method:: m_opt
  63. ...d: A method with optional arguments. Square brackets without a
  64. preceding modifier means that the contents is optional. So in this
  65. case, either no argument must be given, or if one argument is given it
  66. is a, or if two arguments are given, it is a and b in that order.
  67. ...optionals
  68. ....arg: a: int+
  69. ....arg: b: string+
  70. ..method:: m_alt
  71. ...d: A method with alternative arguments.
  72. An
  73. ....sup:
  74. .....strong: alt:
  75. ....t: before the bracket is a modifier that means that there is a
  76. choice of alternatives. The argument is required and should be either
  77. an int+, string+ or list+.
  78. ...alt
  79. ....arg: a: int+
  80. .....d: Description for an int argument.
  81. ....arg: a: string+
  82. .....d: Description for a string argument.
  83. ....arg: a: list+
  84. .....d: Description for a list argument.
  85. ..method:: m_repeat
  86. ...d: A method with repeated arguments.
  87. A modifier
  88. ....sup:
  89. .....strong: m..n:
  90. ....t: before the argument, where m and n are integers, means an
  91. argument that may be repeated at least m times and at most n
  92. times. Instead of n, * may be specified and means any number of times.
  93. ...repeat: 0..*
  94. ....arg: a: int+
  95. .....d: This argument may be repeated any number of times as long as
  96. it is of of kind int+.
  97. ...repeat: 2..4
  98. ....arg: b: string+
  99. .....d: The final arguments must be of kind string+ and be repeated 2,
  100. 3 or 4 times.
  101. ..method:: m_draw_keywords
  102. ...d: A method with optional keyword arguments.
  103. ...d: The modifier
  104. ....sup
  105. .....strong: draw:
  106. ....t: means to 'draw' any combination of arguments from within the
  107. brackets. Keyword arguments by them self would not be optional, but
  108. would be mandatory, in the current specification system.
  109. ...draw
  110. ....key arg: a : int+
  111. ....key arg: b : int+
  112. ....key arg: c : string+
  113. ..method:: range
  114. ...d: A method combining different argument specifications.
  115. ...d: The modifier
  116. ....sup
  117. .....strong: seq
  118. ....t: means arguments that are specified by the
  119. ....em: sequence
  120. ....t: of arguments within the following brackets.
  121. ....p: Create a range of numbers.
  122. ...alt
  123. ....arg: stop: int+
  124. ....seq
  125. .....arg: start: int+
  126. ......d: The first value of the range.
  127. ......default: 0
  128. Starts with first value.
  129. .....arg: stop: int+
  130. ......d: The value just beyond the last value of the range.
  131. .....optionals
  132. ......arg: step: int+
  133. .......d: Positive or negative, steps values up or down.
  134. .......default: 1
  135. ...returns: list_of_integers
  136. ....d: a list containing an arithmetic progression of integers.
  137. .document: docexample
  138. ..output: html, tester
  139. ..man page of: list_of_integers
  140. ..man page of: example_kind
  141. ..test of: example_kind