Is it possible for a crate to hook into the compiler at the point where it knows all the user's function names, and what attributes they have?
I'm experimenting with ways to generate documentation for programs. Rustdoc is great for documenting crates, but doesn't generate documentation geared toward end-users (man pages for CLI programs, or HTML pages for Web APIs written in Rust) I'd like to use the doc comments of various things and generate documentation the program can refer to or embed.
Perhaps this could be done by hooking into Rust's name resolution system during a build. For example, look for a specific function call in main.rs, see what its arguments are (such as passed in function names), and grab those items' doc comments (so, knowing where they were defined).
I think someone mentioned Rustdoc uses a fork of the compiler to accomplish this type of functionality, but I'm curious if it can be done using a build script or some hook or something.
I'm not aware of any straightforward way to achieve what you're asking for, but maybe you're trying to solve some underlying problem that can be approached in a different manner? If you told us more about your use-case, we could point out alternatives and/or focus on how the minimal required amount of "hooking into the compiler"-style behavior your use-case requires could possibly be achieved.
rustdoc has an unstable JSON output mode which allows you to reuse its data collection while generating your own choice of formatting. So, you can use that if the info you want to publish is a subset of what rustdoc collects.
I read about that.. and thanks for the suggestion. I think it's a step in the right direction, but to serialize it to JSON, just to deserialize it back to Rust in order to use it in (compile-time) code or format it however you want seems wasteful..
Think of it as a clean abstraction boundary between your code and the compiler — you won't need to fetch the rustc source and recompile your program (and perhaps make changes to follow redesigns in the compiler) whenever a new Rust release happens.
To add extra emphasis to this: rustc used to support compiler plugins. It intentionally stopped doing that, because coupling external code to the specific implementation details of the compiler was such a mess.
That's why we now have proc macros -- with a specific smaller-but-guaranteed interface -- and various machine readable output formats for things.
You don't want to hook into the compiler if you can possibly avoid it
It's similar to malloc_info story: whole output is clearly designed to be consumable by C programs it's an XML which gives it flexibility needed (it doesn't use JSON simply because when it was added JSON wasn't a thing).
Yes, it sounds a bit silly to pass data in a text format when you can hook directly into a compiler… but this implies much tighter coupling and unless you are doing something extremely performance-sensitive JSON is pretty adequate intermediate format.
