Як використовувати @link та @code у kotlin kDoc

Question 1

Я намагаюся задокументувати метод і намагаюся використовувати, як @linkі @codeв JavaDoc .

Я знаю, що в kotlin є kDoc, але я не можу їх знайти або, принаймні, щось подібне.

Question 2

@linkі @codeне існує в kDoc, але його легко замінити вбудованою розміткою .

Вбудована розмітка

Для вбудованої розмітки KDoc використовує звичайний синтаксис Markdown , розширений для підтримки скороченого синтаксису для зв’язування з іншими елементами коду.

Посилання на елементи

Щоб зв’язати інший елемент (клас, метод, властивість або параметр), просто вкажіть його ім’я у квадратних дужках:

Для цього використовуйте метод [foo].

Якщо ви хочете вказати власну мітку для посилання, використовуйте синтаксис стилю посилання Markdown:

Використовуйте [this method][foo]для цієї мети. Ви також можете використовувати кваліфіковані імена в посиланнях. Зауважте, що на відміну від JavaDoc, кваліфіковані імена завжди використовують крапковий символ для розділення компонентів, навіть перед назвою методу:

Використовуйте [kotlin.reflect.KClass.properties]для перерахування властивостей класу. Імена у посиланнях вирішуються за тими ж правилами, що і якщо ім’я було використано всередині документа, що документується. Зокрема, це означає, що якщо ви імпортували ім’я до поточного файлу, вам не потрібно повністю його кваліфікувати, коли ви використовуєте його в коментарі KDoc.

Зверніть увагу, що KDoc не має жодного синтаксису для вирішення перевантажених членів у посиланнях. Оскільки інструмент генерації документації Kotlin розміщує документацію щодо всіх перевантажень функції на одній сторінці, ідентифікація конкретної перевантаженої функції не потрібна для роботи посилання.

Question 3

Ви можете написати свій код за допомогою Java і перетворити клас на Kotlin.

/**
 * @see <a href="http://somelink.com">link</a>
 */
public class Some {
}

буде перетворено на

/**
 * @see [link](http://somelink.com)
 */
class Some

Question 4

Для {@link SomeClass}на картах Java до [SomeClass]Котліна

Адже {@code true}в Java-картах `true` у Котліні

Question 5

Відповідь , що Артур дав хороший натяк в цілому, але результат не так. Принаймні IntelliJ IDEA не впливає на результат. Формат посилання на націнку, який використовується []()в основному тексті коментаря, але не стосується зовнішніх посилань у @seeтезі. Для них вам потрібен той самий синтаксис, що і в Java:

/**
 * Do something.
 *
 * @see <a href="https://stackoverflow.com/q/45195370/2621917">External links in kdoc</a>
 */

Question 6

Я трохи боровся з цим із Android Studio 3.5.2 на Mac. Це спрацювало для мене:

/**
* [Your fully-qualified class name.function name]
*/

Якби я не використовував повноцінне ім'я, Kdoc скаржився б, що це невирішене посилання. Я не міг зрозуміти, як насправді використовувати саме посилання. Для цього потрібно натиснути і утримувати клавішу COMMAND (на Mac), і тоді посилання будуть активними.

Question 7

Для посилання на метод використовуйте клас :

/**
 * When the configuration succeeds **[MyCallback.onConfigured]** is called.
 */
class MyClass(myCallback: MyCallback) {

Використання змінної / параметра не працює :

/**
 * When the configuration succeeds **[myCallback.onConfigured]** is called.
 */
class MyClass(myCallback: MyCallback) {

Question 8

Що стосується @codeслід використовувати синтаксис Markdown (причина KDoc є розширеною версією Markdown):

Щоб створити блок коду в Markdown, просто відступайте кожен рядок блоку принаймні на 4 пробіли або 1 вкладку.

/**
 * Some code sample:
 * 
 *    Set<String> s;
 *    System.out.println(s);
 */
class Scratch