Kotlin / dokka

API documentation engine for Kotlin
https://kotl.in/dokka
Apache License 2.0
3.43k stars 407 forks source link

Self-closing <p/> tag causing removal of link #369

Closed mathjeff closed 5 years ago

mathjeff commented 6 years ago

Adding the text <p/> into a javadoc can cause Dokka to skip emitting a link. For example, running this script:

/tmp $ cat /tmp/paragraphtest.sh 
#!/bin/bash
set -e

# temp dir
tempDir="/tmp/test"
rm -rf "$tempDir"
mkdir -p "$tempDir"
cd "$tempDir"
subdir="src/androidx/emoji/text"
mkdir -p "$subdir"

# write files
echo 'package androidx.emoji.text;
/**
 * Keeps emojis up to date by adding EmojiSpans to a given {@link CharSequence}. 
 * <p/>
 * EmojiCompat has to be initialized before it can process a {@link CharSequence}.
*/
public class EmojiCompat {
}' > "${subdir}/EmojiCompat.java"
echo 'package androidx.emoji.text;
/**
 * Keeps emojis up to date by adding EmojiSpans to a given {@link CharSequence}. 
 * EmojiCompat has to be initialized before it can process a {@link CharSequence}.
*/
public class EmojiCompat2 {
}' > "${subdir}/EmojiCompat2.java"

# run dokka
java -jar ~/dokka-fatjar-0.9.19-SNAPSHOT.jar src

# search for output
echo
echo Notice that the CharSequence exists only for EmojiCompat2 but not for EmojiCompat
grep --color -ri "Keeps emojis up to date.*CharSequence" out
echo
echo "These are the differences between the files:"
diff -r "${subdir}/EmojiCompat.java" "${subdir}/EmojiCompat2.java"

generates this output:

Module: 
Output: out/doc
Sources: /tmp/test/src
Classpath: 
Analysing sources and libraries... 
done in 3 secs
Generating pages... 
done in 0 secs
generation completed successfully

Notice that the CharSequence exists only for EmojiCompat2 but not for EmojiCompat
out/doc/androidx.emoji.text/index.html:<p>Keeps emojis up to date by adding EmojiSpans to a given <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>. EmojiCompat has to be initialized before it can process a <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>.</p>
out/doc/androidx.emoji.text/-emoji-compat2/-init-.html:<p>Keeps emojis up to date by adding EmojiSpans to a given <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>. EmojiCompat has to be initialized before it can process a <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>.</p>
out/doc/androidx.emoji.text/-emoji-compat2/index.html:<p>Keeps emojis up to date by adding EmojiSpans to a given <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>. EmojiCompat has to be initialized before it can process a <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>.</p>
out/doc/androidx.emoji.text/-emoji-compat2/index.html:<p>Keeps emojis up to date by adding EmojiSpans to a given <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>. EmojiCompat has to be initialized before it can process a <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>.</p>
out/doc/alltypes/index.html:<p>Keeps emojis up to date by adding EmojiSpans to a given <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>. EmojiCompat has to be initialized before it can process a <code><a href="http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html">CharSequence</a></code>.</p>

These are the differences between the files:
4d3
<  * <p/>
7c6
< public class EmojiCompat {
---
> public class EmojiCompat2 {

It'd be great if Dokka would throw an error if <p/> is considered invalid

mathjeff commented 6 years ago

cc @tiembo

kamildoleglo commented 5 years ago

This has been fixed on multiplatform-support