[PATCH] D69545: [globalisel][docs] Rework GMIR documentation and add an early GenericOpcode reference

Daniel Sanders via Phabricator via llvm-commits llvm-commits at lists.llvm.org
Mon Oct 28 20:49:55 PDT 2019


dsanders marked an inline comment as done.
dsanders added inline comments.


================
Comment at: llvm/docs/GlobalISel/GenericOpcode.rst:4
+
+Generic Opcodes
+===============
----------------
arsenm wrote:
> This document brings the number of places documenting the generic opcodes to 3. TargetOpcodes.def attempts to document these, as does GenericOpcodes.td. There's a risk of these becoming out of date and inconsistent with each other. We should probably prune these to have one canonical place for documenting them. Ideally this document would be generated from the comments in either the .td or .def file
I don't think we should count TargetOpcodes.def there. With a couple exceptions, the comments for the G_* instructions more or less re-state the name of the instruction but replaces 'G_' with 'Generic ' and tacks ' instruction' on the end. I think we could delete all of those comments and lose very little. That said, the G_TRUNC description has information that isn't present in GenericOpcodes.td which is interesting.

> There's a risk of these becoming out of date and inconsistent with each other. We should probably prune these to have one canonical place for documenting them.

I agree. Having a one-line summary in each place makes some sense but duplicating the detail is bad. The end goal with the GMIR+GenericOpcodes pages in our sphinx documentation is to end up with the GMIR equivalent of LangRef.rst, giving the high-level picture, how the pieces fit together, and the specification of the GMIR. We can also cross-reference the GMIR+GenericOpcodes to our existing MIR documentation and LLVM-IR where appropriate (e.g. the reference to the LLVM-IR bitcast which G_BITCAST matches).

> Ideally this document would be generated from the comments in either the .td or .def file

I don't really agree with this bit though, the important bit is that there's a single source of truth. There's also some downsides to the generating from comments approach. For example, it actually causes duplication as well as reducing it (although to be fair, this is a problem with the tools available more than an approach). SelectionDAG's ISD::NodeType documentation (https://llvm.org/doxygen/namespacellvm_1_1ISD.html#a22ea9cec080dd5f4f47ba234c2f59110) is a good example of this as the rendered docs is full of holes caused by not duplicating the comment for each enum value and this makes it hard to extract meaning from the rendered docs.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D69545/new/

https://reviews.llvm.org/D69545





More information about the llvm-commits mailing list