Is KDoc ready, documented?

1

Hello,

Can I generate API docs from source, yet? If so, how? Is the format documented somewhere?

thanks,
Rob

2

No, KDoc is stalled. We are developing another tool for the same purpose, but with extended feature set and different architecture. It's not ready yet, but we are close.

3

Okay, thanks. Is the formatting/syntax decided yet? I could use it, even though I can't generate docs yet.

Rob

4

Let me turn the question back to you (and community) :)

What do you think, how should we design syntax, format, etc?

5

I don't have an opinion on basic syntax -- @param (Javadoc) vs param (doxygen), etc. But a couple things I'd like to see...

  1. Allow formatting of comments with something like wiki-text or markdown, at least for basic cases, in addition to the usual HTML/XML tags. The reason: comments with some basic formatting (like lists, headers, code examples) will be more readable in the code editor.

  2. Make it extensible, so we can write Java/Kotlin to customize the HTML (usually) output, beyond what you can do by merely changing a CSS file.

  3. Parse the Kotlin in code examples, so it can have syntax highlighting in the final output.

I know #3 could be tricky, because you hand the compiler a snippet of code with no context. But maybe there is way to set up the context in the comment and mark the part of it that is not meant for display? Brainstorming hereā€¦

/** An example comment. Blah, blah, blah.Ā Ā Hereā€™s how to use a Foo:
Ā Ā <code>
Ā Ā val foo = Foo()Ā Ā /* - /
Ā Ā foo.doStuff(ā€œabcā€, 123)
Ā Ā </code>
/

The /* - */ could be a marker comment.Ā Ā So generated documentation shows only foo.doStuff("abc", 123). The code before the marker exists to give the compiler enough context to parse and highlight the code.Ā Ā The code example could be highlighted in the IDE too, not just in the generated documentation.

Rob

6

+1 to using Markdown (maybe GitHub flavoured Markdown). I read as many Javadoc comments directly in the code as I do in the browser. It would be great if KDoc comments were more readable than Javadoc with embedded HTML. Generics are particularly bad because of the need to escape them.

1 Like
7

Another idea: if the compiler were exposed as a full enough API, it would be relatively easy for people to write documentation generators. I'm imagining some kind of "code DOM" where you can iterate over packages, classes, methods, and comments.

Rob

8

Yes, this is all pretty much like what we did. You can see (very rough) code here: https://github.com/orangy/dokka Here is one example of what it generates: http://kotlinlang.org/api/latest/jvm/stdlib/ To produce it we generate markdown pages (jekyll flavored) and process it through the normal templating. Dokka can generate Html, Markdown and Text, but many things are still half-baked. It can also generate Java and Kotlin signatures for documentation, but Java was not update for some long time.

As usual, it will improve as time permits :slight_smile:

9

+1 Markdown.Ā Ā That makes for much cleaner adding and reading of code examples.

My 2c, Iā€™d have a separate section for Annotation types and Enum types (separate from the other types like javadoc).Ā Ā To me that helps when you ask ā€˜what are all the annotations I can use here ā€¦ā€™

In terms of community contributions, if there was a class or package that was documented really well in terms of style and code examples then it could be used as a model for others to copy for adding more kdoc (it might be just me but Iā€™d like to see more kdoc and code examples added to the standard library ā€¦ Iā€™d tend to drop the use of @includeFunctionBody for now and ā€˜inlineā€™ good code examples with the view that good kdoc with code examples helps adoption).Ā Ā 

Cheers, Rob.