blob: 40eaa80ff62adbaf82e07a256c2456f30b9438a5 (
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
126
127
128
129
130
|
-- :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: 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
-- :BITS: 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
-- 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;
-- :log2: as functions are longer in definitions, it might be written before
function log2(param : positive) return natural;
function log2(
-- :log2: 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;
-- 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;
-- This should allow for any kind of documentation style and embedded documentation language.
-- A real implementation might use similar rules are Python+docutils+Sphinx. Here we would e.g.
-- document a function either before (or inside) a function declaration and use the
-- :arg name: description
-- 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;
|
