Does the FIR have access to the source comments (v...
# compiler
h
Does the FIR have access to the source comments (via KtElement) from another Gradle module, maybe when using friendPath or does the compiler always use the compiled class files?
d
No, it doesn't. Moreover, the PSI (KtElement) is not used by the CLI compiler by default.
😐 1
h
Hm, I generate an OpenAPI file and I analyze the outputs of the functions, but the output class can be declared in another module. And I don't want to analyze all classes from all modules eagerly, but only the needed ones lazily. The current implementation by starting the analysis from the function misses the documentation from classes declared in another module. Would https://youtrack.jetbrains.com/issue/KT-80323 pass the documentation to the compiler or will it be "only" passed to the Analysis API?
d
Currently we are planning to implement generation of the documentation file in this issue based on the analysis api, as this machinery requires to know about all the compilation targets, not just one (as the compiler is usually invoked). cc @Oleg Yukhnevich
o
Hey, yeah, what Dmitriy said is correct. The whole story with doc comments is currently far from ideal (both from the tooling side and in terms of consistency when working with KDocs), I agree, and we are working to improve it. First step was to migrate Dokka to use the Analysis API - the same API that is used now for analysis in the IDE. Previously, those were two separate but partially copied inconsistent implementations. The next step is the documentation model, which will allow any tool (not even written in Kotlin) to work with documentation, even if you don't have sources available (so, for old and new versions or for dependencies). This is what is currently in progress. The next step is potentially the introduction of an API in the Analysis API to access comments: both from sources and from the published documentation model (see KEEP discussion about it). This might also help the IDE get better markdown highlighting (see the comment), though it's not the only way to achieve that, as it could be implemented on top of PSI, which the IDE has access to. This should also cover your use case, as you don't really need a compiler plugin but rather read-only analysis (at least, as far as I understand it). And probably only after that would it make sense to move the KDoc machinery to FIR (see KT-83700). This will allow two things: • working with doc comments on FIR elements, e.g., attaching a comment in the compiler plugin, or modifying it. • re-using the compiler diagnostics layer for KDocs, so that the warnings/errors could be propagated to the Analysis API, and so IDE and other tools build on it. Those are nice things for sure, but I would say they're less important at the moment. As well, if we were to allow modification of comments in compiler plugins, it would mean that sources would become even less representative of what the final users will use. It's already an "issue" that when you navigate to a declaration from a library generated by a compiler plugin, you will have no sources for it, and now the comments could also be "wrong" if they are added or modified. IDEA does a nice thing by showing inlay hints for compiler plugin-generated declarations, but only inside the module, where the compiler plugin is directly applied, and AFAIK, it doesn't work with modified declarations. At some point, the documentation model could solve this issue, as it will include both signatures and doc comments, even for declarations that are not available in the sources. Though it's a long road to get there, as not all of the steps and components I've described here are planned to be done at this point. 🙂 And I haven't even mentioned that KDoc itself needs improvements! Better support for samples or support for referencing overloaded declarations would be nice features that could improve the user experience. Take it as a "bright future" idea, or at least as the direction we are hopefully headed. And, the documentation model here is the first foundation block.
h
Wow, thats an incredible detailed answer, thank you! I am very exited about the future 🙂
kodee loving 1