feat: Extract comments from Java code

[tomdaffurn]

Extract comments from Java code for Verbs, Data, Enum, Config, and Secrets

Closes #2417

Schema for the test data module is:

module javacomments {
  // Config comment
  config config String
  // Secret comment
  secret secretString String
  
  // Comment on a data class.
  export data DataClass {
    field String
  }
  export data EnumType {
    name String
    ordinal Int
  }
  
  // Comment on a verb
  export verb MultilineCommentVerb(javacomments.DataClass) javacomments.EnumType
}

[alecthomas]

Nice! Can we also remove the @param entries?

[tomdaffurn]

Nice! Can we also remove the @param entries?

@alecthomas We can. Do you want to strip all javadoc tags, or just ones that've been extracted for config and secrets?

[stuartwdouglas]

Awesome!

[alecthomas]

Nice! Can we also remove the @param entries?

@alecthomas We can. Do you want to strip all javadoc tags, or just ones that've been extracted for config and secrets?

I think we should delete them, I can't see how they could be useful outside the context of the JVM?

[tomdaffurn]

I think we should delete them, I can't see how they could be useful outside the context of the JVM?

👍 :

• We could be losing significant info by dropping them. Not uncommon for a @param and @return tags to be detailed
• For JVM-JVM dependencies, it would make for full-featured, idiomatic comments

👎 :

• They are ugly and not going to be supported by FTL or Go tooling
• If we're opinionated in dropping them, then Java verb authors will adapt and write comments in a style compatible with all languages

👉 I will delete them. Make a list of common tags and strip them out.

[alecthomas]

We could potentially reconstruct them for the JVM where it makes sense?

[tomdaffurn]

We could potentially reconstruct them for the JVM where it makes sense?

Yeah. Can take comments from the schema for params that FTL has knowledge of: Config, Secrets, the body param, verb clients

[stuartwdouglas]

Some tags will potentially loose information if you delete them, it is not uncommon to have link or code tags in the middle of a sentence, that will no longer make sense if it is removed. Is there a plan for the schema comments to support any sort of markup language? Markdown comments would be kinda cool.

[alecthomas]

No plan but that would be very cool.

[tomdaffurn]

OK, I added tag stripping, and a TODO to extract more info into a potential markdown/rich format schema comment system.