John Snow <js...@redhat.com> writes: > The intent here is to mark only certain definitions as visible in the > end-user docs. > > All commands and events are inherently visible. Everything else is > visible only if it is a member (or a branch member) of a type that is > visible, or if it is named as a return type for a command. > > Notably, this excludes arg_type for commands and events, and any > base_types specified for structures/unions. Those objects may still be > marked visible if they are named as members from a visible type.
Why? I figure the answer is "because the transmogrifier inlines the things excluded". Correct? > This does not necessarily match the data revealed by introspection: in > this case, we want anything that we are cross-referencing in generated > documentation to be available to target. I don't get the part after the colon. > Some internal and built-in types may be marked visible with this > approach, but if they do not have a documentation block, they'll be > skipped by the generator anyway. This includes array types and built-in > primitives which do not get their own documentation objects. > > This information is not yet used by qapidoc, which continues to render > documentation exactly as it has. This information will be used by the > new qapidoc (the "transmogrifier"), to be introduced later. The new > generator verifies that all of the objects that should be rendered *are* > by failing if any cross-references are missing, verifying everything is > in place. So... we decide "doc should be visible" here, and then the transmogrifier decides again, and we check the two decisions match? > Signed-off-by: John Snow <js...@redhat.com>