Improve register list doc design for repeated registers #626
Description
Our tool for generating register reference tables from the VHDL allow for a VHDL doc comment to describe a register that appears in a memory map table organized by address, and optionally provide a brief description for a list that appears below the table organized alphabetically by signal name. In cases where there are multiple instances of a type of register, such as the position of each of eight sprites, we use a doc convention where each register populates the table (S0X, S0Y, S1X, S1Y, etc.) and the only the first register populates the list (SNX, SNY) to avoid unnecessary repetition in the list.
This convention has several disadvantages:
- It's difficult to associate the memory map entry with the description list entry via a text search in a PDF viewer. (S0X does not appear in the list.)
- It's difficult to find the corresponding description for a memory map entry because it is unintuitive how the entry is sorted or spelled in the description list. (It is not obvious that the description for S0X is found at "SNX.")
- There are egregious cases where the repeated register layout has two dimensions, and we don't have a clear convention for this.
This will become less of an issue once we have richer reference prose and tutorial chapters, relieving some of the burden on these tables to fully communicate complex concepts. We still need these tables and lists to be accurate and concise.
We should iterate on some design improvements, then improve our tools and conventions accordingly. The doc comment syntax should group signals mechanically, so the LaTeX generator (document-memory.c) can render register groups in a more user friendly way. A simple example solution—not necessarily my favorite—would be to list every signal in a group on a single description bullet, describe it with typographical hints, and alphabetize it by its first entry:
