Documentation out of date

[jordancarlin]

The ExtendingGuide in docs/ has fallen pretty far out of date. It refers to files that no longer exist (riscv_csr_ext.sail, riscv.sail, etc.), outdated virtual memory functions (checkPTEPermission), and uses the N extension as its example, which is no longer in the model.

There are also several newer things that are required to add a new extension that are not covered in the guide, like the extensionEnabled enum.

[jordancarlin]

The ReadingGuide has similar issues with broken links and references to nonexistent files.

[Timmmm]

Yeah I vote to just remove them. This sort of documentation always falls out of date in my experience. It stands a much better chance as comments in the code. Maybe some of the content could be translated to comments.

[jordancarlin]

I was leaning towards removing them as well, but wasn’t sure if people thought it was worth maintaining the Extending Guide as a way for new contributors to get started adding extensions. That being said, I don’t think I looked at it when I was getting going so not sure how useful it really is.

[billmcspadden-riscv]

Topic for next Mondays meeting, yes?

…

On Tue, Dec 31, 2024, 4:44 PM Jordan Carlin ***@***.***> wrote: I was leaning towards removing them as well, but wasn’t sure if people thought it was worth maintaining the Extending Guide as a way for new contributors to get started adding extensions. That being said, I don’t think I looked at it when I was getting going so not sure how useful it really is. — Reply to this email directly, view it on GitHub <#660 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AXROLOHRTY6HRDAJKDO2XO32IMM3PAVCNFSM6AAAAABUN47VA2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKNRWG42DCMJRGM> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[jordancarlin]

Per discussion during today's meeting, we are going to keep the documentation because we think it is still worthwhile to new contributors and users.

I will add a warning to the documentation for now to warn users that it is not up to date and will start to work through updating parts of it that are obviously wrong.

@edolnx is going to look at tooling to help notify us when the documentation falls out of date and potentially to extract some of it directly from the code.