Working Group - Quarkus Config and IDEs

[gsmet]

Hi,

With the introduction of the new extension annotation processor in Quarkus 3.14, we now have a comprehensive and structured model of our configuration properties when we build the extensions.

This model is used to generate the Asciidoc documentation but it can also be used to generate files embedded in the extension jars that could be consumed by IDEs to provide information about the available configuration.

We won't generate a file per IDE/IDE plugin so we need to define a common format that works well for everyone.

Tip

You can find a summary of the discussions in the In the previous episodes... section below.
I will update it regularly.

Current situation

We generate a file named META-INF/quarkus-javadoc.properties that is embedded in the jar and contains the javadoc of the config in the standard Properties format.

There is no other information so, if an IDE wants to get an idea of the available configuration properties, they have to go through the config classes and extract the configuration properties themselves.

This is not sustainable, error prone and duplicate efforts, especially since the Quarkus config has a lot of advanced features and it's hard to stay on top of them.

What we aim for

The main goal of this working group is to define a common format describing the Quarkus properties, format that could be consumed by all IDEs.

Constraints

Warning

If you arrive now, skip this paragraph, it contains some constraints that we will probably alleviate given the discussions we had.

• The files must be generated by the extension annotation processor
• The files may be in either the runtime or the associated -deployment module, depending on where the config root is: IDEs will have to scan both
• The javadoc must be in a separate file (but not necessarily a .properties as we might want to embed more information in it)
• The javadoc of a given property won't always be in the same artifact, the javadoc values must be merged in a map prior to being consumed (some config roots use config groups that are in other modules)
• The model may contain the deprecated properties in a way that makes them identifiable - we could also include the @deprecated note in the model to point to the new property.
• The generated files must be very simple and easily consumable - we don't want the IDEs to have to reimplement the logic leading to the model: ideally we would generate a list of all existing properties already expanded.
• The generated files must be in a structured format, preferably JSON or YAML - to be defined depending on what's easier to consume

Outputs

• A fully specified format for the generated files embedded in the jar
• Clear guidelines on how to consume these files
• At least one implementation in a Quarkus plugin

How to proceed

If you are interested in this initiative, please add a comment here and I will include you in the discussions about the format.

Once the format is defined, the implementation in the annotation processor should be fairly easy.

In the previous episodes...

Note

I will try to summarize the discussions here as we make progress.

Consensus

• There seems to be a consensus that it would be nice to use the Spring format for config metadata (as documented here).
• The format would need to augmented with some additional Quarkus metadata. The Quarkus-specific metadata will be in a separate namespace to avoid future conflicts (i.e. in a quarkus node for instance).
• While not in the Spring format, the properties will contain an additional sourceField/sourceMethod to indicate the source element of the property. This field will be added at the root so that's it's close to sourceType.
• Loading things from runtime and deployment dependencies is annoying and can be slow.
• We will attach an additional artifact to the -deployment module. This artifact will contain the config metadata in the Spring format (+ some additional Quarkus-specific metadata). So for each runtime extension (ie any jar having a META-INF/quarkus-extension.properties in it), IDEs will download an additional artifact with name <extension>-deployment-<version>-config-metadata.json. IDEs don't need to download the deployment artifacts to get the configuration properties, just these additional JSON files. The file might not contain properties if the extension doesn't have any configuration properties but it will exist.
• The Javadoc included in these files will be converted to Markdown prior to inclusion in the files.

Remaining constraints

• The config metadata for an extension cannot be embedded in the runtime artifact (i.e. in quarkus-core for instance). The reason is that part of the config is in the -deployment artifact and the -deployment artifact depends on the runtime one. This is not going to change.

Exploration and ideas

• It would be nice to include better support for deprecation and we probably need an annotation in Quarkus to handle that better.

Experiments

The latest status of the experiments has been posted here: #42671 (comment) .

[gsmet]

/cc @angelozerr @fbricon @wglanzer

[wglanzer]

@angelozerr @fbricon I think you should support it in your plugin! My plugin may be deprecated in the future, because yours is able to do anything my plugin does. Just saw and realized that..

[maxandersen]

@wglanzer which plugin is your making ?

[wglanzer]

@maxandersen Just a small "run configs" plugin, because those were missing initially. https://plugins.jetbrains.com/plugin/14242-quarkus-run-configs

[maxandersen]

Ah cool!

[gsmet]

I published a very quick experiment here which can give an idea of the information we need to include: #42677 .

Note that this is just an experiment to give you an idea of the data we need to include in the output.
It might not be completely comprehensive though as we need to discuss how to handle the maps and free form maps, and probably a lot of other things :).

Still, I think it's useful to understand what is specific to Quarkus.
One important thing is that the Javadoc is in Asciidoc.

The result of this experiment is the following files:
quarkus-ide-experiments.zip

You can for instance have a look at those of hibernate-validator to have a simple example and those of hibernate-search-orm-elasticsearch to have an example that is a bit more complex with maps.

[aloubyansky]

What I meant was we could "extract" the code that you maintain fetching Quarkus extension metadata into a library (a Maven artifact) and make it a project under quarkusio org. You would add that library as a dependency and call some API on it. The rest would be impl details.

Having metadata stored in Quarkus extension JAR is a better idea I think.

The way it's evolving, it will have to be in the deployment jar (in the best case just in the deployment JAR, in the worst you would have to look for data in multiple places: runtime + deployment classpath).
That means you will need to find the deployment JARs, for which you will need to identify the runtime extension JARs first.
Then as you mentioned downloading deployment JARs isn't looking ideal either.
Theoretically, it should be possible to group the IDE-related metadata in a single JSON per extension and publish it as a Maven artifact. You would still need to identify the runtime extension artifacts to figure out how to get the IDE metadata for them though.

There are various implementation options to consider. So I was wondering if defined a Java API and hid the impl details behind it for you. Would that help?

[angelozerr]

What I meant was we could "extract" the code that you maintain fetching Quarkus extension metadata into a library (a Maven artifact) and make it a project under quarkusio org. You would add that library as a dependency and call some API on it. The rest would be impl details.

For scanning Java classes and libraries, we don't use Java Reflection, but we use the search API and Java classes visitor provided by the IDE (JDT for Eclipse and vscode) and (PsiFile for IntelliJ) which provides fast performance and avoid building and maintaining a Java classpath on each change of classpath.

More we use this scanning Java classes for Java sources too.

The way it's evolving, it will have to be in the deployment jar (in the best case just in the deployment JAR, in the worst you would have to look for data in multiple places: runtime + deployment classpath).
That means you will need to find the deployment JARs, for which you will need to identify the runtime extension JARs first.
Then as you mentioned downloading deployment JARs isn't looking ideal either.

We already do that :

• step1: we scan classpath to collect runtime JARS
• step2: for each runtime JAR we check if it exists the quarkus-extension.properties file and the declared deployment-artifact property (ex : deployment-artifact=io.quarkus:quarkus-undertow-deployment:0.21.1)
• step3: we donwload the deployment JAR and add it to the search classpath
• step4: we visit all classes of the search classpath to collect properties from libraries and sources.

If we could have a metada JSON file stored in the Quarkus runtime (properties from runtime + deployment) which contains:

• the properties declared in Java classes from the runtime
• the properties declared in Java classes from the deployment
• the properties declared in Java classes from deployment JARS which reference the deployment of the runtime (ex : kubernetes Quarkus extension)

it will avoid doing step2, step3, step4 (for libraries). step for sources will be required again but it is very fast.

Theoretically, it should be possible to group the IDE-related metadata in a single JSON per extension and publish it as a Maven artifact.

If you mean having a metada JSON file for a given Quarkus runtime (properties from runtime + deployment), it is the thing that will improve performance.

You would still need to identify the runtime extension artifacts to figure out how to get the IDE metadata for them though.

You mean storing this metadata JSON file in an another artifact, why not storing this metadata JSON file in the runtime?

There are various implementation options to consider. So I was wondering if defined a Java API and hid the impl details behind it for you. Would that help?

As I tried to explain you, we need to be fast and use IDE API to get classpath and visit libraries.

[aloubyansky]

If we provided a JSON (or properties) with all the necessary metadata for a Quarkus extension found in a project, would you still need to scan both the runtime and deployment classpath for Quarkus metadata?

The way I imagine it, in the best case scenario, there could be a single metadata file per Quarkus extension but it can't be in the runtime JAR. In that best case scenario, you would perform

• step1
• in step2 you would either get link to the deployment JAR containing that unified metadata file(s) or get a link to another JSON Maven artifact containing the unified metadata.
• step3 you would obtain and read the metadata
• would step4 still be necessary?

[angelozerr]

If we provided a JSON (or properties) with all the necessary metadata for a Quarkus extension found in a project, would you still need to scan both the runtime and deployment classpath for Quarkus metadata?

No, I need to investigate more but I think the slowdown comes from building custom search classpath with deployment JARs.

The way I imagine it, in the best case scenario, there could be a single metadata file per Quarkus extension but it can't be in the runtime JAR. In that best case scenario, you would perform

Indeed it was my idea!

would step4 still be necessary?

Yes to collect properties from Java sources and other properties from MicroProfile (with @ConfigProperty).

[maxandersen]

+1 for not having a Quarkus version specific jar added to tools. Fine tools reads metadata from extensions but generally really bad to have runtimes jar dependency in tools. It would need to be able to work with multiple version of Quarkus and Java versions. Even more than any Quarkus release will.

[cescoffier]

I love this idea!

[angelozerr]

Thank you very much @gsmet for creating this wonderful discussion that we have been waiting for a very long time.!

Having the properties available for a Quarkus extension could perhaps improve the performance of loading the properties available for the application.properties file (to manage completion, validation, hover, etc.), but the biggest difficulty for us is the management of Quarkus deployments which slow down the project loading performance.

Indeed we have coded in JDT Eclipse and IJ the downloads of the Quarkus deployments and then added them to the search classpath to find the properties of the Quarkus deployment.

This works but can degrade performance. For performance reasons we do not look for Quarkus deployments that reference the Quarkus deployment of an extension, and in this case we lose properties.

An example is the Quarkus Kubernetes extension. We had to hard code the fact that we have to look for Quarkus deployments that reference the root Quarkus deployment.

As language server uses JSON to coomunicate with LSP client (vscode, IJ, Eclipse IDE, etc) we use JSON as format to describe properties. We generate this JSON metadata by scanning Java classes by using MicroProfile annotations (ex: Configproperty) or Quarkus annotations. When some properties cannot be retrieved by annotations, we hard coded in JSON files.

You can find them:

• for MicroProfile at https://github.com/eclipse/lsp4mp/tree/master/microprofile.jdt/org.eclipse.lsp4mp.jdt.core/static-properties
• for Quarkus at https://github.com/redhat-developer/quarkus-ls/tree/master/quarkus.jdt.ext/com.redhat.microprofile.jdt.quarkus/static-properties.

Here the sample for config_ordinal MicroProfile property:

{
	"properties": [
		{
			"type": "java.lang.Integer",
			"extensionName": "microprofile-config-api",
			"required": false,
			"name": "config_ordinal",
			"description": "`config_ordinal` can be set within any built-in `ConfigSource` implementation. The default implementation of `getOrdinal()` will attempt to read this value. If found and a valid integer, the value will be used. Otherwise the respective default value will be used."
		}
	]
}

I have tried to follow the same format than Spring https://www.baeldung.com/spring-boot-configuration-metadata#generating-metadata (but I had to add some new property like sourceField, extensionName, etc)

Ideally what we would need is to have a JSON file (which has the same format as I gave above) stored in the Quarkus extension JAR that describes all the properties of the extension and includes those of the deployment JARs (it would be amazing for us to have this and it would considerably boost the loading of properties!)

I hope I explained our need correctly and we are very excited to use the mechanism you intend to implement.

Thanks for thinking of us (IDE support)!

[maxandersen]

Remember @angelozerr that these deployment jars are needed to build Quarkus app anyway so it should not bring overhead to tools (except the project is not built yet)

[angelozerr]

Remember @angelozerr that these deployment jars are needed to build Quarkus app anyway so it should not bring overhead to tools (except the project is not built yet)

Loading the proper deployment by using the properties file stored in runtime which declares it in this properties file is not a problem.

If the deployment contains all java classes to compute quarkus properties, it works perfectly and we dont loose quarkus properties.

The problem comes from when this deployment depends on another artifacts which can contain java classes which must generate quarkus properties. We need to resolve them with maven / gradle and load them again to add them to the classpath to compute the quarkus properties.

This dependencies resolve can take a lot of time. A sample is quarkus kubernetes which defines a deployment which must be resolved again to add for instance io.dekorate.* which defines java classes which generates quarkus properties.

If we could avoid resolving those dependencies and just loading a deployment or another thing to collect all quarkus properties for a given runtime it will improve a lot of performance and will avoid loosing quarkus properties.

We loose quarkus properties because we have hard coded the fact that only quarkus kubernetes deployment must be resolved to avoid having a very bad performance.

[gsmet]

We know that people will end up having to download the deployment dependencies when building/running the app.

But I think it has value to not do it right away and be able to import the project and start coding without having to download a lot more dependencies.
Same when you add one: it's nice to be reactive and just download what you need for the classpath + config.

That's where having small dedicated JSON files shine because you don't have to go through downloading a bunch of jars (and it can be quite some jars) but just download a few JSON files and parse them.

[maxandersen]

Yes - I get that part but important we check why that overhead is that big. IDE tooling does it iteratively all the time.

Having separate artifact definitely can make sense but if we do that would it make sense we make an archive with combined metadata rather than having one for individual items ?

[aloubyansky]

One of the issues is that IDEs probably won't resolve the deployment dependencies Quarkus would. For example, they would have to enforce proper BOMs (which I am not sure they do) that could result extra downloads and lead to differences in the resulting set of artifacts.

[aloubyansky]

Constraints

Are these hard requirements or points to discuss?

The files must be generated by the extension annotation processor

AFAIU, this is for specific types of metadata, right? This one still seems more like an implementation detail to me.

The files may be in either the runtime or the associated -deployment module, depending on where the config root is: IDEs will have to scan both

As @angelozerr suggests, I think this should be discussed further. We could certainly produce a single file per extension for IDEs to consume.

We could possibly generate a file from the deployment module and push it to a separate artifact but I'm not sure it would get any better

I think it'd be worth exploring it. It'd be a lot less painful to consume for an IDE than a deployment JAR.

(we would need to add an additional Maven plugin to each deployment module I think).

This seems to fit the direction of @holly-cummins 's ADR, so we could put a start to it with this effort?

It would certainly not get any better from a Quarkus POV.

Let's consider the big picture though. Thanks for starting this discussion.

[aloubyansky]

I wanted to add another requirement: IDEs sjouke aware of conditional dependencies whose conditions are satisfied.

Conditional dependencies is a core feature that's not going away, in fact it seems it's getting more popular. It should be taken into account in the design phase of a contract.

For that reason I'd suggest considering the Gradle Tooling API approach (https://docs.gradle.org/current/javadoc/org/gradle/tooling/GradleConnector.html)
We could have Quarkus Tooling API that IDEs could use to load a Quarkus project model with actual Quarkus application build classpath and metadata.

Conditional dependencies won't be present during the compile phase of a project (at least that's how it is today) but they will certainly contribute config properties and other extensions metadata.

[aloubyansky]

What do you think about this one @gsmet ?

[gsmet]

Hmmm, I actually wrote something about it yesterday but apparently I closed my tab without posting...

So my personal opinion is that:

• even if we implement this, we also need a simple Quarkus onboarding for IDEs that doesn't require too much work to get a quick win - thus why I would push to publish the metadata anyway
• then, while I can see the value of it, every time I import a Gradle project in my IDE, I have issues. Most of the time it doesn't work well. On rare occasions, I end up with a working workspace. So if we go this way, I would like us to try hard to keep it simple so that it's actually rock solid and never is in the way.

Now, this is really a comment as an end user, I haven't looked at the detail of this connector.

[aloubyansky]

The actual experience loading Gradle project models using the connector API is not a great one in a sense it's quite slow, since it actually launches a Gradle process and some build tasks.
But conceptually, for Quarkus that's probably the way. It will require dependency resolution, so on the first run it may be pretty slow but it will prefetch everything and that cache will be re-used for subsequent builds, etc. Once the model has been resolved, it should be fast enough.

[maxandersen]

Gradle tooling api is extremely expensive and result in massive inefficiencies if done naively.

IDEs already are engaging with maven and Gradle so before we consider having yet another integration here I would like to understand why/if tooling team are seeing an expected slowdown (quakrus projects simply need more jars downloaded) or some bad missing optimization that can be fixed.

[gsmet]

I played a bit more with my experiment following the feedback here as I wanted to check how hard it would be to go with another approach. I pushed my new stuff here: #42677 .

The main idea of this new approach is:

• we generate an assembled metadata JSON when building the deployment artifact. It is deployed as a separate artifact (for instance quarkus-hibernate-validator-deployment-999-SNAPSHOT-config-metadata.json). It contains all the configuration properties of this extension (build time and runtime). It also contains the Javadoc.
• the generated JSON follows the Spring format with a few Quarkus additions (and I will need to collect a few additional things on my side too): it contains the properties and the hints for the enum values.
• I don't generate the groups for now, I'm not sure how useful they are to you, I probably could.

This is just an experiment and very much in flux.
For each Quarkus extension in the classpath, you would have to get this file from the Maven repo. I'm not sure if its something easy peasy in the IDE world or if it's complex. We need feedback on this.

The downside on the Quarkus side is that we would need to add a plugin execution to each extension deployment module. But we might need to do that anyway for other purposes.
Another downside is that I had to publish the YAML model in the jars, which I avoided until now. We could either do that or find another solution but I need to be able to collect them whether the dependencies are in the reactor or not.

Here is the result of this experiment on three extensions:

quarkus-ide-experiments-2.zip

[gsmet]

@angelozerr would it be a problem if sourceField and sourceMethod were under the quarkus node?

I'm a bit reluctant to add fields that are not in the Spring spec outside of our own namespace.
I could be convinced for these ones though as they are very close to sourceClass and it would probably be weird to have sourceClass at the root and sourceField and sourceMethod under quarkus.

Maybe you could actually ask the Spring team to add them if they are useful for you?.

[angelozerr]

@angelozerr would it be a problem if sourceField and sourceMethod were under the quarkus node?

Spring Metadata uses sourceType and sourceMethod but not sourceField. Why you don't want to follow the same format?

sourceField doesn't exist,perhaps because Spring doesn't provide this feature?

[gsmet]

It is defined in the groups but not in the properties: https://docs.spring.io/spring-boot/specification/configuration-metadata/format.html .

In the properties, only sourceType is defined. Thus why I asked.

[angelozerr]

Ohh you are right! Idon't know why propeties doesn't define sourceMethod.

We need to ask to Spring guys.

[maxandersen]

@angelozerr since Quarkus projects need the deployment jar anyway is there an advantage to have the file separate for the IdE?

[gsmet]

I summarized the status of the discussions in the In the previous episodes... section of the top description. I'll try to keep it up to date.

[angelozerr]

Thanks so much @gsmet

Next week I will investigate again what is slow when we load properties and give you feedback.

Having a separate artifact which contains only json metadata can be a good idea.

I think we should take as sample the quarkus kubernetes extension which was a nightmare for us because the runtime references a deployment which references other deployments. It means that deployment artifacts must be resolved by maven or gradle to know the other deployment which must be downloaded and performance was so bad that we give up this resolution.

We download the deployment and that is all. To support correctly kubernetes extension we have hard coded the deployments to download. It is very uggly but it provides better performance.

But for other extensions which have deployment which references other deployments (I think quinoa have that but not sure) we loose the properties. It is very bad.

So if we could have an artifact to download for a given runtime which contains json metadata for the deployment and other deployments which are referenced it will avoid for us to hard code the deployments to download. It is a very important point for IDE.

[angelozerr]

@gsmet could you do your experimentation with kubernetes openshift extension.

For IDE this extension is a nightmare,because we need to download the kubernetes openshift deployment which defines some properties, but too download other depdencies deployment like quarkus-container-image-openshift-deployment, io.dekorate, etc.

To collect all artifact to scan to collect properties, we have started to resolve it with maven , but it was so long. It is the reason why we have hard coded those dependencies to know which deployment JARs must be downloadedfrom a givendeployment JAR in https://github.com/redhat-developer/intellij-quarkus/blob/821038d1e707fa8e523a918a13576884f862cb59/src/main/java/com/redhat/devtools/intellij/quarkus/buildtool/BuildToolDelegate.java#L44 for kubernetes.

If we could get properties from a given runtime for deployment + dependencies deployment in the same JAR, it would be fantastic.

[gsmet]

@angelozerr so in this case, here is how it would work:

• you list all the runtime dependencies and collect the Quarkus extensions (i.e. a jar with a quarkus-extension.yaml in it)
• this will include quarkus-openshift and also quarkus-container-image-openshift
• for each extension, you will try to download a file extension-deployment-VERSION-config-metadata.json (name might change but you get the idea): these files will contain the configuration properties.
• you don't have to scan anything else
• you don't need to download the deployment artifacts - that being said the user will need to download them when they build the app

[angelozerr]

you list all the runtime dependencies and collect the Quarkus extensions (i.e. a jar with a quarkus-extension.yaml in it)

If we could have quarkus-extension.properties it would be easier for us, because we will not need to use an external library to parse YAML format, but it is doable.

this will include quarkus-openshift and also quarkus-container-image-openshift

If I understand for a given runtime, we need to read the quarkus-extension.yaml which will store a list of quarkus extensions (runtime + deployments) and we don't need to read those runtime + deployments to retrieve all other extensions which are referenced (like dekorate), is that?

If it that it should be fantastic.

for each extension, you will try to download a file extension-deployment-VERSION-config-metadata.json (name might change but you get the idea): these files will contain the configuration properties.

If I understand correctly, we will need to loop for the list of runtime + deployments stored in quarkus-extension.yaml download for each item of the list the proper extension-deployment-VERSION-config-metadata.json

No problem for that.

[maxandersen]

@gsmet didnt we agree on having deployment recorded in properties file in runtime (also) or did we just discuss that ?

if we had that IDE would have these fairly easy and just look them up and if done after maven/Gradle run it should not be slow (and if done before tools can bulk reesolve rather than one by one)

[gsmet]

I have a question about the format of the maps, which are VERY often used in Quarkus (for instance when you have several datasources, persistence units, clients...).

In the files I generate atm, they look like this:

quarkus.hibernate-orm."persistence-unit-name".packages

I know I have seen files @angelozerr was using that had the maps with things like [*] for the keys.

Which is a bit unfortunate for two reasons:

• it's not how you define them in Quarkus
• you lose an important information as the key gives you some nice information about what's needed there

Interested in your feedback @angelozerr and @aleksey-stukalov .

[angelozerr]

I know I have seen files @angelozerr was using that had the maps with things like [*] for the keys.

Indeed I have used that because Quarkus generated that on Quarkus project start. We use [*] to know that user can fill the propertywith any content, but I agree that we loose some helpfull information and it would be very nice if we could imagine an expression which will help IDE to know how to fill this information (ex : fill with class name, we could provide Java classes completion, validation fill with class name which extends some interface, we could provide completion, validation for classes which extends the given interface) and more.

We need to list usecases. Ex : persistence-unit-name means that we need to scan classes which are annotated with some interface (perhaps?)

[gsmet]

We need to list usecases. Ex : persistence-unit-name means that we need to scan classes which are annotated with some interface (perhaps?)

I think this part can probably be done in a second time - it might be references to some annotation, it might be some reference to another map of the config.
Basically we would need to make sure the names are consistent everywhere in the doc and then we could imagine teaching the IDEs how to get the possibilities depending on the name.
But it's a bit orthogonal to how we feed you the properties though.

[angelozerr]

I think this part can probably be done in a second time - it might be references to some annotation, it might be some reference to another map of the config.

Exactly, for the moment if you can generate the same format that we use it will be nice.

[gsmet]

And I think I have one last important question: the format of the actual doc.

In Quarkus, we are using both traditional HTML based Javadoc and Asciidoc (we have a marker in the doc to differentiate them). For inclusion in our doc, we translate the HTML based Javadoc to Asciidoc. So for our internal doc, we have everything Asciidoc (but our translator is not exactly perfect).

We also know that there will be some Markdown Javadoc support coming soon in the JDK (we might not use it in Quarkus but some extensions outside of Quarkus might use it).

I was wondering if you were able to display Asciidoc and Markdown in the IDE? Markdown, I'm pretty sure, Asciidoc I'm not so sure.

Also I think we should have a marker of the format so that you can pick the right renderer?

Finally are you able to render traditional Javadoc without the full context: for instance, let's say it's the Javadoc of a deployment class and you have a {@link otherClass}, it doesn't seem sound to download the deployment classpath just to render the Javadoc.
Should we filter those on our side and push you a {@code type} instead?

Interested in your feedback @angelozerr and @aleksey-stukalov .

Once this and the map format are sorted out, I think we could prototype something great for Quarkus 3.16.

[angelozerr]

I was wondering if you were able to display Asciidoc and Markdown in the IDE? Markdown, I'm pretty sure, Asciidoc I'm not so sure.

No, LSP support only plaintext and markdown. So please use MarkDown otherwise we will need to translate Asciidoc -> MarkDown (bad for performance and dangerous because we could loose some information while converting).

[gsmet]

Well, we have Asciidoc and that won't change. Our Quarkus documentation is Asciidoc and we wanted the ability to pass Asciidoc as is from config to the doc.
This is a feature we want and need in Quarkus.

Now I could handle the transformation of the subset of Asciidoc we have to Markdown. It won't be perfect, sometimes it might end up with some badly formatted things but it will work most of the time and be good enough as we don't do crazy things either.
At some point, we have to find a balance between our constraints and yours.
If you have a link for the Markdown flavor supported in LSP, that would be awesome as each implementor has usually its own additions.

Now I have a question about your plaintext thing, is it actual plain text or it it traditional HTML Javadoc? Because I suppose you are able to render traditional HTML javadoc, right?

[angelozerr]

If you have a link for the Markdown flavor supported in LSP, that would be awesome as each implementor has usually its own additions.

There is not really a spec for MarkDown in LSP since each LSP client (vscode, IJ, EclipseIDE, etc) have their own MarkDown parser. So it should support all MarkDown specification (according the limitation of the LSP client).

Now I have a question about your plaintext thing, is it actual plain text or it it traditional HTML Javadoc? Because I suppose you are able to render traditional HTML javadoc, right?

plaintext is used when you want generate a simple content (without link , without styles, etc) and when your LSP client cannot support MarkDown. But for our case, we use markdown because LSP client that we use (vscode, IJ, Eclipse IDE) supports MarkDown. So let's generate doc with MarkDown.

[gsmet]

@angelozerr by any chance, do you know an easy way for me to test what is supported for the Markdown? Typically, we have some advanced tables in Asciidoc and the only way to render them would be to use plain HTML tables. It's for instance supported by GitHub but I'm not sure it's supported in the IDEs.

If you have an easy way to test that directly in an IDE, that would be awesome. Maybe it's using the same engine for the Markdown preview?

[angelozerr]

Each LSP client (vscode, Eclipse IDE with LSP4E, IntelliJ with LSP4IJ) uses given markdown parser wriiten in Java, TypeScript, etc:

• in vscode if I remember it uses https://github.com/markedjs/marked so you could play with https://marked.js.org/demo/
• in Eclipse IDE (LSP4E° theu use the Mylin WikiEdit
• in IJ with LSP4IJ we use FlexMark

So you could have different behaviour. I noticed that our Quarkus Tooling escape markdown character from Javadoc, so for the moment it will not work (I need to discuss with my team about this choice).

In vscode, I suggest to follow this idea:

• create a TypeScript file test.file which contains some markdown content in the JSDoc:

/**
 * `abcd`

| Aligné à gauche  | Centré          | Aligné à droite |
| :--------------- |:---------------:| -----:|
| Aligné à gauche  |   ce texte        |  Aligné à droite |
| Aligné à gauche  | est             |   Aligné à droite |
| Aligné à gauche  | centré          |    Aligné à droite |
 */
function foo() {}

foo();

• hover the foo function, you should see the rendered markdown: