I'm trying to document a method and trying to use #link and #code as in JavaDoc.
I know in kotlin there is a kDoc but I can't find them or at least something similar.
#link and #code doesn't exist in kDoc but can easily be replaced by Inline Markup.
from KotlinDoc Linking to Elements
Inline Markup
For inline markup, KDoc uses the regular Markdown syntax, extended to
support a shorthand syntax for linking to other elements in the code.
Linking to Elements
To link to another element (class, method, property or parameter),
simply put its name in square brackets:
Use the method [foo] for this purpose.
If you want to specify a custom
label for the link, use the Markdown reference-style syntax:
Use [this method][foo] for this purpose. You can also use qualified
names in the links. Note that, unlike JavaDoc, qualified names always
use the dot character to separate the components, even before a method
name:
Use [kotlin.reflect.KClass.properties] to enumerate the properties of
the class. Names in links are resolved using the same rules as if the
name was used inside the element being documented. In particular, this
means that if you have imported a name into the current file, you
don't need to fully qualify it when you use it in a KDoc comment.
Note that KDoc does not have any syntax for resolving overloaded
members in links. Since the Kotlin documentation generation tool puts
the documentation for all overloads of a function on the same page,
identifying a specific overloaded function is not required for the
link to work.
For {#link SomeClass} in Java maps to [SomeClass] in Kotlin
For {#code true} in Java maps to `true` in Kotlin
You can write your code with java and convert class into Kotlin.
/**
* #see link
*/
public class Some {
}
will be converted to
/**
* #see [link](http://somelink.com)
*/
class Some
The answer that Artur gave is a good hint in general, but the result is wrong. At least IntelliJ IDEA does not grok the result. The markdown link format using []() is fine in the main comment text, but not for external links in the #see tag. For those, you need the same syntax as in Java:
/**
* Do something.
*
* #see External links in kdoc
*/
I struggled with this for a bit with Android Studio 3.5.2 on Mac. This worked for me:
/**
* [Your fully-qualified class name.function name]
*/
If I didn't use the fully-qualified name Kdoc would complain that it was a unresolved reference. What I couldn't figure out is how to actually use the link itself. For that you need to press and hold the COMMAND key (on Mac) and then the links would be active.
To reference a method use the class:
/**
* When the configuration succeeds **[MyCallback.onConfigured]** is called.
*/
class MyClass(myCallback: MyCallback) {
Using a variable/parameter does not work:
/**
* When the configuration succeeds **[myCallback.onConfigured]** is called.
*/
class MyClass(myCallback: MyCallback) {
It seems we should just use a markdown hyperlink without any special tags such as #see or #link:
/**
* This is a doc.
*
* See [this](https://google.com)
* And [this](https://stackoverflow.com)
*/
fun myfun() {}
This doc renders in following way in IDE:
As for the #code you should use Markdown syntax (cause KDoc is an extended version of Markdown):
To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab.
/**
* Some code sample:
*
* Set<String> s;
* System.out.println(s);
*/
class Scratch
Sample how to leave links for classes:
/**
* [YourClass] Methods
* */
also with method calls
/**
* [YourClass.someMothod] Methods
* */
Real example:
/**
* [BaseActivity] Methods
* */
override fun initVars() {
//Just Sample
}
/**
* [MainContract.View] - Overrides
* */
override fun handleConnectionMassage(isShow: Boolean) {
//Just Sample
}
Related
I used to reference methods in Java Doc like this:
/**
* #see com.myapp.view.fragment.PlaybackControlFragment#onPlaybackStateChanged
*/
I don't know how to reference same method in kotlin?
The part com.myapp.view.fragment.PlaybackControlFragment is linked however method name is not clickable and link.
What is the right syntax?
Just change # to . and it will work correctly.
/**
* #see com.myapp.view.fragment.PlaybackControlFragment.onPlaybackStateChanged
*/
is it possible to define something like macros in Doxygen?
I want write a comment something like this:
/**
\return return_self_reference
*/
and Doxygen will replace return_self_reference with a string defined by me.
The comment that would then be read by Doxygen would be this one:
/**
\return A reference to the instance that the operator was called on.
*/
Please note that, alltough I called it a macro earlier, I do not want to define a C macro or anything like that in the actual code.
Doxygen has for these cases the configuration parameter ALIASES.
Lets take the following example:
/** \file
*/
/**
* \return the normal version
*/
int fie0(void);
/**
* \return \str1_repl
*/
int fie1(void);
/**
* \str2_repl
*/
int fie2(void);
and set the following ALIASES in the doxygen configuration file (see also the manual for more possibilities of ALIASES):
ALIASES = "str1_repl=just the text in replacement" \
"str2_repl=\return return and the text in replacement"
and we will get the following result:
Let's say there's a class which primary constructor has the parameter param that I'd like to be resolved (linked to the actual parameter) within the doc block of the class.
/** Class A does something using [param].
#constructor constructs A with [param].
*/
class A (param: Int)
However, the inscription param is highlighted by the IDE saying that it cannot resolve symbol param.
Actually, dokka correctly finds the parameter if you reference it with [param] in the #constructor paragraph, you can check that by inspecting the URL that appears in the assembled docs, which looks like:
file:///.../some.package/-a/-init-.html#some.package.A$<init>(kotlin.Int)/param
Seemingly, the warning about an unresolved reference is an issue with the IDE support for KDoc. Please report it at kotl.in/issue.
Another option is to use #param in the class KDoc:
/**
* Class A does something using [param].
* #param param means something special.
*/
class A (param: Int)
How do you generate comments for your methods/classes? Simply typing:
/**
And pushing enter does not seem to work in IntelliJ IDEA 2016.1.3
It seems like Dokka has superseded KDoc, but why is there no support in IntelliJ? Or am I missing something?
Clarification: when typing in /** + enter, this gets generated:
/**
*
*/
But I'm wondering why the generation of #param and others aren't added (like IntelliJ does for Java). These annotations are used for documenting Kotlin code as well (https://kotlinlang.org/docs/reference/kotlin-doc.html)
To expand on #yole's answer and #Charles A.'s comment, here is a full explanation of the preferred format when creating KDocs and how it differs from JavaDocs.
The Kotlin documentation here:
https://kotlinlang.org/docs/reference/coding-conventions.html#documentation-comments
...says:
Generally, avoid using #param and #return tags. Instead, incorporate the description of parameters and return values directly into the documentation comment, and add links to parameters wherever they are mentioned. Use #param and #return only when a lengthy description is required which doesn't fit into the flow of the main text.
Avoid doing this:
/**
* Returns the absolute value of the given number.
* #param number The number to return the absolute value for.
* #return The absolute value.
*/
fun abs(number: Int) = ...
Do this instead:
/**
* Returns the absolute value of the given [number].
*/
fun abs(number: Int) = ...
The #param and other tags are not generated because the recommended documentation style for Kotlin is to refer to parameter names from the doc comment text using the [foo] syntax, rather than to document them using explicit #param tags. You can check the Kotlin standard library documentation to see how this style is used.
When declaring a module that extends dojo/Stateful, the pattern for getters and setters is to defined _xxxGetter and _xxxSetter which will be manifested as .get('xxx') and .set('xxx').
So, my question is, how best to document this with JSDoc? #function doesn't appear to support providing alternate method names and, in anyway, this is a variation on parameter values, not method names?
So, does JSDoc have any inherent support for this model, or do I just need to write explicit documentation for this stuff?
So if its for generating docs alone? Try this: https://github.com/jsdoc3/jsdoc
It is now possible to stack multiple documentation blocks pr variable / function. Dont hang my head on this - but i would believe syntax is like such:
{
...
/**
* Get varname property
* #returns {mixed}
*//**
* Set varname property
* #param {mixed} val
* #returns {this}
*/
varname: null
...
}