blob: 3f7fdc44c7ec56de2bac6a221ccc4fe4b8d0fa6f (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
-- :e1: comments before desIgn units (javadoc / .net documentation style)
-- :e1: mIGht be multiline
entity e1 is
end entitY;
-- :a1: comments before design units
-- :a1: might be multiline
architecture a1 of e1 is
begin
end architecture;
-- :p1: comments before design units
-- :p1: might be multiline
package p1 is
end package;
--! :ctx1: package body should be supported too to keep parity, but I have currently no usecase for it.
-- :ctx1: comments before design units
-- :ctx1: might be multiline
context ctx1 is
end context;
-- :cfg1: comments before design units
-- :cfg1: might be multiline
configuration cfg1 of e1 is
for a1
end for;
end configuration;
library ieee;
use ieee.std_logic_1164.all;
entity e2 is
-- :e2: comments in design units (python doc-string style)
-- :e2: might be multi line
generic (
-- :FREQUENCY: comment before a generic
-- :FREQUENCY: might be multiline
constant FREQUENCY : positive;
constant BITS : positive; -- :BITS: comment after a generic are mostly single line,
-- :BITS: but could be multi line too
-- :DEBUG: in case comment is before and after
constant DEBUG : boolean -- :DEBUG: the after has presidency
);
port (
signal Clock : in std_logic -- :Clock: same as for generics
);
end entity;
architecture a2 of e2 is
-- :a2: comments in design units (python doc-string style)
-- :a2: might be multi line
begin
end architecture;
-- :p2: As packages define public elements like constants, types and sub-programs, we are interested in such documentation too.
package p2 is
-- :p2: comments in design units (python doc-string style)
-- :p2: might be multi line
-- :DEBUG: comment before
constant DEBUG : boolean := TRUE;
constant SYNC_STAGES : positive := 3; -- :SYNC_STAGES: comment after
-- :AType1: comment before
type AType1 is array(natural range <>) of bit;
type AType2 is array(natural range <>) of bit; -- :AType2: comment after
--! :AType2: same applies to subtype, alias, attributes, ...
-- :RType: comment before
type RType is record
-- :RType: xor comment inside
-- :elem1: per element comment before (note the comment "block" is separated by newlines)
elem1 : integer;
elem2 : integer; -- :elem2: per element comment behind
end record;
--! :elem2: as functions are longer in definitions, it might be written before
function log2(param : positive) return natural;
function log2(
--! :param1: otoh, we also want to document parameters too (similar to a record with comments)
-- :param1: comment before
param1 : integer;
param2 : boolean -- :param2: comment after
) return natural;
--! :param2: this applies to procedures as well.
end package;
context ctx2 is
-- :ctx2: comments in design units (python doc-string style)
-- :ctx2: might be multi line
end context;
configuration cfg2 of e2 is
-- :cfg2: comments in design units (python doc-string style)
-- :cfg2: might be multi line
for a2
end for;
end configuration;
--! :cfg2: This should allow for any kind of documentation style and embedded documentation language.
--! :cfg2: A real implementation might use similar rules are Python+docutils+Sphinx. Here we would e.g.
--! :cfg2: document a function either before (or inside) a function declaration and use the
--! :cfg2: :arg name: description
--! :cfg2: syntax.
-- :math: Package `math` provides math extensions not provided by the IEEE packages.
package math is
-- :log2: Computes the logarithm to base 2.
-- :log2:
-- :log2: :arg param: Input value
-- :log2: :returns: Logarithm
function log2(param : positive) return natural;
end package;
|
