Giters

p4lang / p4c

P4_16 reference compiler

Home Page:https://p4.org/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Consider merging two different doc files on p4c IR into one

jafingerhut opened this issue · comments

commented

@AdarshRawat1 This is primarily for you to think about, but I would guess @fruffy may have some good suggestions here.

There are two *.md files describing the P4C intermediate representation (IR):

  • docs/IR.md
  • ir/README.md

While it is not absolutely necessary to merge them into one somehow, it seems like it might be worth considering if that would be better when browsing/reading the docs.

commented

I agree, it would be beneficial to combine them so that there will be only one source to keep track of P4C intermediate representation (IR) details .

commented

I think there's a place for both.

  • ir/README.md should have a short description of concept of .def files and the ir-generator tool that generates C++ code from them, as well as a summary of what files are in this directory and why -- basically what someone new to the code base who comes looking for the definition of IR::Expression or some such needs to know. It should have a pointer to docs/IR.md for more details
  • docs/IR.md should have the details of the IR classes and how one adds more (backend specific) .def files and IR classes, along with more detail about what methods/useful stuff ir-generator generates from the .def files. It should also describe the Visitor infrastructure (perhaps just a summary with a pointer to a separate file with more details.) This is for someone who already understands the basic structure of the compiler and wants to know how to add more stuff for their backend.

That's not to say what is currently in these files is at all adequate -- more (and better organized) documentation is always a good thing.

commented

If they are kept separate, it would be nice in the doxygen output if they were adjacent to each other.

commented

Closing this issue, as even though these two pages remain separate, for which there are good reasons to do so mentioned by Chris Dodd in his comment above, they are now adjacent in the navigation bar in the latest version as of 2024-Jul-21 here: https://p4lang.github.io/p4c/index.html