Add a documentation for CombInit

[ronan-lashermes]

Documenting CombInit, since I stumble upon it and I did not see any description in the docs.

[andreasWallner]

Thanks a bunch for adding this, I added a few suggestions.

[andreasWallner]

We could add an example here for one of the major use-cases which is to make helper functions that break the reference to the original signal. That would explain what to use it for, I found it's pretty rare in "normal" HDL code. A dumb example would be:

// note that condition is an elaboration time constant
def invertedIf(b: Bits, condition: Boolean): Bits = if(condition) { ~b } else { CombInit(b) }

where we shouldn't return just b in the false case as that would create weird behavior (if true the return value can't influence the original b, if false it can)
Do you think that makes sense?

[ronan-lashermes]

Thanks for your suggestions.
I like your invertedIf example, I was looking for a simple realistic use case : this is it.

[ronan-lashermes]

See 6222df6 for a first try.

[andreasWallner]

I think this is more a statement about references than CombInit - but I have no big issue keeping it if you think it helps a bunch.

[ronan-lashermes]

Yeah, 148 and 149 are a bit redundant with the earlier CombInit description.
151 was there to insist on the differences in the synthesis results, I would like to keep it but add a bit more contextual description.

[ronan-lashermes]

Cf 6222df6.

[andreasWallner]

Thanks!