This repository was archived by the owner on Jul 6, 2026. It is now read-only.
Repository navigation
This repository was archived by the owner on Jul 6, 2026. It is now read-only.
Support documentation formating for Javadoc #3258
Description
To support this test case: https://github.com/microsoft/typespec/pull/8929/files
Java doc should support bullet points, number list, bold and italic styles written in the case.
Reacted by Copilot
Metadata
Metadata
Labels
No labels
Activity
weidongxu-microsoft commentedon Jan 14, 2026
I think Java does not need to have logic to convert markdown to e.g.
<ul><li>.If we had a scoping in spector cases, we can flag it "non-Java".
We only need to verify the Javadoc is valid. It's fine to just do a manual run of
mvn javadoc:javadocin test folder.haolingdong-msft commentedon Jan 14, 2026
thanks Weidong Xu (@weidongxu-microsoft) for the input.
I'm a bit confused. From the parent issue description, it said the case needs to be supported. So I'm working on supporting it.
I did a manual run of
mvn javadoc:javadoc, the output javadoc is like below, which you can see this is not bullet point, italic style or number list format document. Do you mean it is acceptable?I may be lack of context on this, is this something already have or we need to ask for adding this flag?
haolingdong-msft commentedon Jan 14, 2026
Just checked with Renhe Li (@lirenhe), language specific configuration on the dashboard is in progress. So from my understanding, we may not have this flag for now. Weidong Xu (@weidongxu-microsoft) Please let me know if you have more information and let me know what shall I do here.
weidongxu-microsoft commentedon Jan 14, 2026
Yes, it is acceptable. I don't know where the case comes from, but Javadoc does not support Markdown yet.
There may be something in Java 25 https://docs.oracle.com/en/java/javase/23/javadoc/using-markdown-documentation-comments.html
But we are not there yet.
I think put this issue to backlog should be enough for now.
haolingdong-msft commentedon Jan 14, 2026
Weidong Xu (@weidongxu-microsoft) ok, actually I created PR already as the issue description said to support the case... microsoft/typespec#9368. Please let me know if I should close it or continue work on it.
weidongxu-microsoft commentedon Jan 14, 2026
This code handles a limited cases in existing test, and it may fail on corner cases that does not work as expected. E.g.
<-- I don't sure whether this fails, or whether there will be other cases that might fail
Personally, I'd avoid code that just target a test. (unless the ask is only to support that few limited pattern from markdown)
haolingdong-msft commentedon Jan 14, 2026
Yea, it only supports limited case. Then I will close this PR based on your suggestion. Thanks!
haolingdong-msft commentedon Jan 14, 2026
Also close this sub issue as not planned for now, we can create one when there is real use case. Weidong Xu (@weidongxu-microsoft) please let me know if you have any concern.