could you give an example of how code to use that api might look like?
Sorry, but my high-level description will have to do. It's not rocket surgery in any way, but it's also not any simpler or more convenient to use than it looks like.
the thing that i am concerned about is, that people would have to make sure they use the right way, if they want to provide the docs and a simple compile_file() or compile_string() or even cast to program would not cut it anymore.
Indeed it wouldn't, and it can't in any real-world case, where doc extraction, after all, isn't the main thing a program does, or even a remotely common thing. The cost of tapping the source all the time is absolutely nowhere near in proportion to the gain, not even in an application where you would find it nice to provide an integrated API doc browsing feature (and that isn't just a playground like hilfe).
I.e. even if you were to provide a function like OnlinePikeDoc.compile_string_and_tap_source which would be a source-tapping alternative to compile_string, I couldn't use it on, say, the modules in Roxen to make an API doc browser in the admin interface. The sources have to be reloaded on demand only.
i'd like to be able to go into any existing pike application, add a setting or line of code in the beginning and then be sure to not miss any docs from there on.
This would be much like turning on extra debug modes, I take it: I.e. being able to investigate apps without changing them. Sure, I don't have a problem with that, as long as it defaults to off. A define would be best since it means zero runtime overhead when not used.