ScalaDocs improvement for utils Math, MixedVec #1019
Conversation
|
I was also supposed to write docs for Lookup, but I think we should have a discussion on whether to keep those in util, since I'm not sure if they're used, and they seem like very special-purpose constructs that might be better done by composing other functionality like PriorityMux and Vec. |
| * This will be deprecated when zero-width wires is supported. | ||
| * | ||
| * @example {{{ | ||
| * log2Up(1) = 1 |
There was a problem hiding this comment.
Should the example be executable? Maybe something like assert(log2Up(1) == 1)
There was a problem hiding this comment.
Do we have stylistic conventions on that? That's probably good to figure out.
There was a problem hiding this comment.
Fixed. Didn't realize this was a blocking issue. I opted to put the return value in comments because the assert is not part of the example.
| * zero-width wires. | ||
| * | ||
| * @example {{{ | ||
| * log2Up(1) = 0 |
There was a problem hiding this comment.
Isn't this object log2Ceil?
|
Didn't we discuss putting docs in objects vs. methods during the beginning of the meeting (if that was changed later, then I probably missed it)? I think the reasoning was so that you don't have to expand the function defs when you navigate to the object page. |
|
Yeah, put it into the objective and not the method if you have big examples. Take a look at how it comes out in the scaladoc. |
|
Is there anything blocking review approval for this PR? |
|
Poke? |
Adds recommended usage and examples to the Math utils (log2* and isPow2).
Slight improvement to documentation for MixedVec, primarily deduping method ScalaDoc into the object / class ScalaDoc, and clarifying wires / types.
Related issue: #411
Type of change: other enhancement
Impact: no functional change
Development Phase: implementation
Release Notes
Scaladocs for Math (log2*, isPow2) and MixedVec.