Update TopEntity annotation docs to include Enable parameter

[christiaanb]

Fixes #654

[leonschoorl]

There are a couple of examples like:

clash-compiler/clash-prelude/src/Clash/Annotations/TopEntity.hs

Lines 278 to 280 in a737df6

	-- {\-\# ANN topEntity (defSyn "f") \#-\}
	-- f :: Int -> T -> (T,Bool)
	-- f a b = ...

Those ANNotations should be on f, not topEntity.

[christiaanb]

There are a couple of examples like:

clash-compiler/clash-prelude/src/Clash/Annotations/TopEntity.hs

Lines 278 to 280 in a737df6

	-- {\-\# ANN topEntity (defSyn "f") \#-\}
	-- f :: Int -> T -> (T,Bool)
	-- f a b = ...

Those ANNotations should be on f, not topEntity.

I've now updated those as well

[leonschoorl]

I was just trying the first example of Portname:

data T = MkT Int Bool

{-# ANN f (defSyn "f") #-}
f :: Int -> T -> (T,Bool)
f a b = (b,True)

First of all the output doesn't match what is in the documentation:

entity f is
  port(a      : in signed(63 downto 0);
       b_0    : in signed(63 downto 0);
       b_1    : in boolean;
       result : out std_logic_vector(65 downto 0));
end;

But what is surprising is that it unpacks the input T into two ports, but not the output T.

[leonschoorl]

The later examples are also slightly wrong, clash doesn't use types like f_types.t or f_types.tup2 anymore on ports of top entities, they're now always basic VHDL types like std_logic_vector.

[christiaanb]

@leonschoorl can you just fix the issues yourself? :)

[christiaanb]

But what is surprising is that it unpacks the input T into two ports, but not the output T.

That's because defSyn doesn't annotate the arguments; making Clash default to its unannotated behavior: which is to split product types into smaller parts. However, the output must be annotated (just because of how the data type is defined), and defSyn uses PortName "", which tells clash to use a single port for the result.

Perhaps we should use Maybe PortName for the t_output, and then when it's Nothing we could have Clash default to its unannotated behavior: splitting product types into smaller parts. But that's something for a different PR perhaps, although changing the type definition is not really worth it, as most people that care will pick a proper result port annotation.

[leonschoorl]

I went through all the examples in the TopEntity module and updated them and their output.
Now it also fixes #646