Add explanation for Class and Object, with examples.

[mikeurbach]

Contributor Checklist

• Did you add Scaladoc to every public function/method?
• Did you add at least one test demonstrating the PR?
• Did you delete any extraneous printlns/debugging code?
• Did you specify the type of improvement?
• Did you add appropriate documentation in docs/src?
• Did you request a desired merge strategy?
• Did you add text to be included in the Release Notes for this change?

Type of Improvement

• Documentation or website-related

Desired Merge Strategy

• Squash: The PR will be squashed and merged (choose this if you have no preference).

Release Notes

Reviewer Checklist (only modified by reviewer)

• Did you add the appropriate labels? (Select the most appropriate one based on the "Type of Improvement")
• Did you mark the proper milestone (Bug fix: 3.6.x, 5.x, or 6.x depending on impact, API modification or big change: 7.0)?
• Did you review?
• Did you check whether all relevant Contributor checkboxes have been checked?
• Did you do one of the following when ready to merge:
  • Squash: You/ the contributor Enable auto-merge (squash), clean up the commit message, and label with Please Merge.
  • Merge: Ensure that contributor has cleaned up their commit history, then merge with Create a merge commit.

[tymcauley]

Thanks so much for putting together this documentation! It's really great to see how some of these new features are intended to be used.

[tymcauley]

Should these be annotated with @public?

[mikeurbach]

Yeah, maybe they should. Nothing in the example accesses them at Chisel time, but they'd need to be @public if so.

[mwachs5]

is it important to show the @INSTANTIABLE and @public in this simple example...? It seems to be mixing concepts. The important thing here is that it is an IO(Output(Property...)), right?

Maybe the @instantiable/@public could be a follow-on example that says this stuff works with D/I?

[mikeurbach]

Yeah, there is a tension here between the simplest example, and making something that is safe. We have safe and unsafe APIs for creating objects. The unsafe API is useful if you don't know the fields a-priori, like if you're generating the classes/objects from some other data structure. The safe API is literally just Instance, and we declare some helper methods on Instance[T <: Class] using an implicit class. I wanted the first example to show the safe APIs, but that does mean we need @public on at least the input ports to be able to connect to them on the Instance.

[sequencer]

Thanks for the clear documentation. LGTM, I'll propose a end-to-end demonstration recently.

[sequencer]

Currently, we don't have the API to get the hypothetical JSON representation. we can demo it in the panamaom framework.

[mikeurbach]

Yeah that would be great. I will update the wording here slightly, since panamaom isn't an "external tool". Maybe we can add an example in this section of the doc showing a concrete use of panamaom with this IR. It could traverse the descriptions and print something out, so we could show the code snippet and the expected output, or something like that.

[sequencer]

Thanks for @mikeurbach's work! Ask @SpriteOvO to copy&paste the examples to scala-cli test, so we can use the binding framework testing it.