diff options
author | Marcin Aman <marcin.aman@gmail.com> | 2020-10-30 19:01:09 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-10-30 19:01:09 +0100 |
commit | 1aba0ec4973d7915caa93f1e9b3146ad82111903 (patch) | |
tree | b9424de4bc22f8453ecb32aaa8f7f020bcd49e9f /plugins/base/src/test/kotlin/content | |
parent | da498f50eabfad8969eb7795a535e97f7e25ca58 (diff) | |
download | dokka-1aba0ec4973d7915caa93f1e9b3146ad82111903.tar.gz dokka-1aba0ec4973d7915caa93f1e9b3146ad82111903.tar.bz2 dokka-1aba0ec4973d7915caa93f1e9b3146ad82111903.zip |
Fix parsing first word in deprecated (#1595)
Fix parsing first word in `Deprecated` annotations, fix `Throws` and `See` tags
Diffstat (limited to 'plugins/base/src/test/kotlin/content')
3 files changed, 705 insertions, 19 deletions
diff --git a/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt b/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt index efe8949c..4108af82 100644 --- a/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt +++ b/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt @@ -7,12 +7,14 @@ import org.jetbrains.dokka.model.dfs import org.jetbrains.dokka.model.doc.DocumentationNode import org.jetbrains.dokka.model.doc.Param import org.jetbrains.dokka.model.doc.Text +import org.jetbrains.dokka.pages.ContentDRILink import org.jetbrains.dokka.pages.ContentPage import org.jetbrains.dokka.pages.MemberPageNode import org.jetbrains.dokka.testApi.testRunner.AbstractCoreTest import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull import org.junit.jupiter.api.Test import utils.* +import kotlin.test.assertEquals class ContentForParamsTest : AbstractCoreTest() { private val testConfiguration = dokkaConfiguration { @@ -150,7 +152,7 @@ class ContentForParamsTest : AbstractCoreTest() { +"Woolfy" } } - unnamedTag("Since") { comment { +"0.11" } } + unnamedTag("Since") { comment { +"0.11" } } } } } @@ -175,7 +177,8 @@ class ContentForParamsTest : AbstractCoreTest() { """.trimIndent(), testConfiguration ) { pagesTransformationStage = { module -> - val classPage = module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage + val classPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage classPage.content.assertNode { group { header { +"DocGenProcessor" } @@ -218,7 +221,8 @@ class ContentForParamsTest : AbstractCoreTest() { """.trimIndent(), testConfiguration ) { pagesTransformationStage = { module -> - val classPage = module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage + val classPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage classPage.content.assertNode { group { header { +"DocGenProcessor" } @@ -246,6 +250,682 @@ class ContentForParamsTest : AbstractCoreTest() { } @Test + fun `deprecated with multiple links inside`() { + testInline( + """ + |/src/main/java/sample/DocGenProcessor.java + |package sample; + |/** + | * Return the target fragment set by {@link #setTargetFragment}. + | * + | * @deprecated Instead of using a target fragment to pass results, the fragment requesting a + | * result should use + | * {@link java.util.HashMap#containsKey(java.lang.Object) FragmentManager#setFragmentResult(String, Bundle)} to deliver results to + | * {@link java.util.HashMap#containsKey(java.lang.Object) FragmentResultListener} instances registered by other fragments via + | * {@link java.util.HashMap#containsKey(java.lang.Object) FragmentManager#setFragmentResultListener(String, LifecycleOwner, + | * FragmentResultListener)}. + | */ + | public class DocGenProcessor { + | public String setTargetFragment(){ + | return ""; + | } + |} + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val classPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage + classPage.content.assertNode { + group { + header { +"DocGenProcessor" } + platformHinted { + group { + skipAllNotMatching() //Signature + } + group { + comment { + +"Return the target fragment set by " + link { +"setTargetFragment" } + +"." + } + } + group { + header(4) { +"Deprecated" } + comment { + +"Instead of using a target fragment to pass results, the fragment requesting a result should use " + link { +"FragmentManager#setFragmentResult(String, Bundle)" } + +" to deliver results to " + link { +"FragmentResultListener" } + +" instances registered by other fragments via " + link { +"FragmentManager#setFragmentResultListener(String, LifecycleOwner, FragmentResultListener)" } + +"." + } + } + } + } + skipAllNotMatching() + } + } + } + } + + @Test + fun `deprecated with an html link in multiple lines`() { + testInline( + """ + |/src/main/java/sample/DocGenProcessor.java + |package sample; + |/** + | * @deprecated Use + | * <a href="https://developer.android.com/guide/navigation/navigation-swipe-view "> + | * TabLayout and ViewPager</a> instead. + | */ + | public class DocGenProcessor { } + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val classPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage + classPage.content.assertNode { + group { + header { +"DocGenProcessor" } + platformHinted { + group { + skipAllNotMatching() //Signature + } + group { + header(4) { +"Deprecated" } + comment { + +"Use " + link { +"TabLayout and ViewPager" } + +" instead." + } + } + } + } + skipAllNotMatching() + } + } + } + } + + @Test + fun `deprecated with an multiple inline links`() { + testInline( + """ + |/src/main/java/sample/DocGenProcessor.java + |package sample; + |/** + | * FragmentManagerNonConfig stores the retained instance fragments across + | * activity recreation events. + | * + | * <p>Apps should treat objects of this type as opaque, returned by + | * and passed to the state save and restore process for fragments in + | * {@link java.util.HashMap#containsKey(java.lang.Object) FragmentController#retainNestedNonConfig()} and + | * {@link java.util.HashMap#containsKey(java.lang.Object) FragmentController#restoreAllState(Parcelable, FragmentManagerNonConfig)}.</p> + | * + | * @deprecated Have your {@link java.util.HashMap FragmentHostCallback} implement + | * {@link java.util.HashMap } to automatically retain the Fragment's + | * non configuration state. + | */ + | public class DocGenProcessor { } + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val classPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage + classPage.content.assertNode { + group { + header { +"DocGenProcessor" } + platformHinted { + group { + skipAllNotMatching() //Signature + } + group { + comment { + group { + +"FragmentManagerNonConfig stores the retained instance fragments across activity recreation events. " + } + group { + +"Apps should treat objects of this type as opaque, returned by and passed to the state save and restore process for fragments in " + link { +"FragmentController#retainNestedNonConfig()" } + +" and " + link { +"FragmentController#restoreAllState(Parcelable, FragmentManagerNonConfig)" } + +"." + } + } + } + group { + header(4) { +"Deprecated" } + comment { + +"Have your " + link { +"FragmentHostCallback" } + +" implement " + link { +"java.util.HashMap" } + +" to automatically retain the Fragment's non configuration state." + } + } + } + } + skipAllNotMatching() + } + } + } + } + + @Test + fun `multiline throws with comment`() { + testInline( + """ + |/src/main/java/sample/DocGenProcessor.java + |package sample; + | public class DocGenProcessor { + | /** + | * a normal comment + | * + | * @throws java.lang.IllegalStateException if the Dialog has not yet been created (before + | * onCreateDialog) or has been destroyed (after onDestroyView). + | * @throws java.lang.RuntimeException when {@link java.util.HashMap#containsKey(java.lang.Object) Hash + | * Map} doesn't contain value. + | */ + | public static void sample(){ } + |} + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val functionPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" }.children.single { it.name == "sample" } as ContentPage + functionPage.content.assertNode { + group { + header(1) { +"sample" } + } + divergentGroup { + divergentInstance { + divergent { + skipAllNotMatching() //Signature + } + after { + group { pWrapped("a normal comment") } + header(4) { +"Throws" } + platformHinted { + table { + group { + group { + link { +"java.lang.IllegalStateException" } + } + comment { +"if the Dialog has not yet been created (before onCreateDialog) or has been destroyed (after onDestroyView)." } + } + group { + group { + link { +"java.lang.RuntimeException" } + } + comment { + +"when " + link { +"Hash Map" } + +" doesn't contain value." + } + } + } + } + } + } + } + } + } + } + } + + @Test + fun `multiline kotlin throws with comment`() { + testInline( + """ + |/src/main/kotlin/sample/sample.kt + |package sample; + | /** + | * a normal comment + | * + | * @throws java.lang.IllegalStateException if the Dialog has not yet been created (before + | * onCreateDialog) or has been destroyed (after onDestroyView). + | * @exception RuntimeException when [Hash Map][java.util.HashMap.containsKey] doesn't contain value. + | */ + | fun sample(){ } + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val functionPage = + module.children.single { it.name == "sample" }.children.single { it.name == "sample" } as ContentPage + functionPage.content.assertNode { + group { + header(1) { +"sample" } + } + divergentGroup { + divergentInstance { + divergent { + skipAllNotMatching() //Signature + } + after { + group { pWrapped("a normal comment") } + header(4) { +"Throws" } + platformHinted { + table { + group { + group { + link { + check { + assertEquals( + "java.lang/IllegalStateException///PointingToDeclaration/", + (this as ContentDRILink).address.toString() + ) + } + +"java.lang.IllegalStateException" + } + } + comment { +"if the Dialog has not yet been created (before onCreateDialog) or has been destroyed (after onDestroyView)." } + } + group { + group { + link { + check { + assertEquals( + "java.lang/RuntimeException///PointingToDeclaration/", + (this as ContentDRILink).address.toString() + ) + } + +"java.lang.RuntimeException" + } + } + comment { + +"when " + link { +"Hash Map" } + +" doesn't contain value." + } + } + } + } + } + } + } + } + } + } + } + + @Test + fun `multiline throws where exception is not in the same line as description`() { + testInline( + """ + |/src/main/java/sample/DocGenProcessor.java + |package sample; + | public class DocGenProcessor { + | /** + | * a normal comment + | * + | * @throws java.lang.IllegalStateException if the Dialog has not yet been created (before + | * onCreateDialog) or has been destroyed (after onDestroyView). + | * @throws java.lang.RuntimeException when + | * {@link java.util.HashMap#containsKey(java.lang.Object) Hash + | * Map} + | * doesn't contain value. + | */ + | public static void sample(){ } + |} + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val functionPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" }.children.single { it.name == "sample" } as ContentPage + functionPage.content.assertNode { + group { + header(1) { +"sample" } + } + divergentGroup { + divergentInstance { + divergent { + skipAllNotMatching() //Signature + } + after { + group { pWrapped("a normal comment") } + header(4) { +"Throws" } + platformHinted { + table { + group { + group { + link { + check { + assertEquals( + "java.lang/IllegalStateException///PointingToDeclaration/", + (this as ContentDRILink).address.toString() + ) + } + +"java.lang.IllegalStateException" + } + } + comment { +"if the Dialog has not yet been created (before onCreateDialog) or has been destroyed (after onDestroyView)." } + } + group { + group { + link { + check { + assertEquals( + "java.lang/RuntimeException///PointingToDeclaration/", + (this as ContentDRILink).address.toString() + ) + } + +"java.lang.RuntimeException" + } + } + comment { + +"when " + link { +"Hash Map" } + +" doesn't contain value." + } + } + } + } + } + } + } + } + } + } + } + + + @Test + fun `documentation splitted in 2 using enters`() { + testInline( + """ + |/src/main/java/sample/DocGenProcessor.java + |package sample; + |/** + | * Listener for handling fragment results. + | * + | * This object should be passed to + | * {@link java.util.HashMap#containsKey(java.lang.Object) FragmentManager#setFragmentResultListener(String, LifecycleOwner, FragmentResultListener)} + | * and it will listen for results with the same key that are passed into + | * {@link java.util.HashMap#containsKey(java.lang.Object) FragmentManager#setFragmentResult(String, Bundle)}. + | * + | */ + | public class DocGenProcessor { } + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val classPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage + classPage.content.assertNode { + group { + header { +"DocGenProcessor" } + platformHinted { + group { + skipAllNotMatching() //Signature + } + group { + comment { + +"Listener for handling fragment results. This object should be passed to " + link { +"FragmentManager#setFragmentResultListener(String, LifecycleOwner, FragmentResultListener)" } + +" and it will listen for results with the same key that are passed into " + link { +"FragmentManager#setFragmentResult(String, Bundle)" } + +"." + } + } + } + } + skipAllNotMatching() + } + } + } + } + + @Test + fun `multiline return tag with param`() { + testInline( + """ + |/src/main/java/sample/DocGenProcessor.java + |package sample; + | public class DocGenProcessor { + | /** + | * a normal comment + | * + | * @param testParam Sample description for test param that has a type of {@link java.lang.String String} + | * @return empty string when + | * {@link java.util.HashMap#containsKey(java.lang.Object) Hash + | * Map} + | * doesn't contain value. + | */ + | public static String sample(String testParam){ + | return ""; + | } + |} + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val functionPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" }.children.single { it.name == "sample" } as ContentPage + functionPage.content.assertNode { + group { + header(1) { +"sample" } + } + divergentGroup { + divergentInstance { + divergent { + skipAllNotMatching() //Signature + } + after { + group { pWrapped("a normal comment") } + group { + header(4) { +"Return" } + comment { + +"empty string when " + link { +"Hash Map" } + +" doesn't contain value." + } + } + header(2) { +"Parameters" } + group { + platformHinted { + table { + group { + +"testParam" + comment { + +"Sample description for test param that has a type of " + link { +"String" } + } + } + } + } + } + } + } + } + } + } + } + } + + @Test + fun `return tag in kotlin`() { + testInline( + """ + |/src/main/kotlin/sample/sample.kt + |package sample; + | /** + | * a normal comment + | * + | * @return empty string when [Hash Map](java.util.HashMap.containsKey) doesn't contain value. + | * + | */ + |fun sample(): String { + | return "" + | } + |} + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val functionPage = + module.children.single { it.name == "sample" }.children.single { it.name == "sample" } as ContentPage + functionPage.content.assertNode { + group { + header(1) { +"sample" } + } + divergentGroup { + divergentInstance { + divergent { + skipAllNotMatching() //Signature + } + after { + group { pWrapped("a normal comment") } + group { + header(4) { +"Return" } + comment { + +"empty string when " + link { +"Hash Map" } + +" doesn't contain value." + } + } + } + } + } + } + } + } + } + + @Test + fun `list with links and description`() { + testInline( + """ + |/src/main/java/sample/DocGenProcessor.java + |package sample; + |/** + | * Static library support version of the framework's {@link java.lang.String}. + | * Used to write apps that run on platforms prior to Android 3.0. When running + | * on Android 3.0 or above, this implementation is still used; it does not try + | * to switch to the framework's implementation. See the framework {@link java.lang.String} + | * documentation for a class overview. + | * + | * <p>The main differences when using this support version instead of the framework version are: + | * <ul> + | * <li>Your activity must extend {@link java.lang.String FragmentActivity} + | * <li>You must call {@link java.util.HashMap#containsKey(java.lang.Object) FragmentActivity#getSupportFragmentManager} to get the + | * {@link java.util.HashMap FragmentManager} + | * </ul> + | * + | */ + |public class DocGenProcessor { } + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val classPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage + classPage.content.assertNode { + group { + header { +"DocGenProcessor" } + platformHinted { + group { + skipAllNotMatching() //Signature + } + group { + comment { + group { + +"Static library support version of the framework's " + link { +"java.lang.String" } + +". Used to write apps that run on platforms prior to Android 3.0." + +" When running on Android 3.0 or above, this implementation is still used; it does not try to switch to the framework's implementation. See the framework " + link { +"java.lang.String" } + +" documentation for a class overview. " //TODO this probably shouldnt have a space but it is minor + } + group { + +"The main differences when using this support version instead of the framework version are: " + } + list { + group { + +"Your activity must extend " + link { +"FragmentActivity" } + } + group { + +"You must call " + link { +"FragmentActivity#getSupportFragmentManager" } + +" to get the " + link { +"FragmentManager" } + } + } + } + } + } + } + skipAllNotMatching() + } + } + } + } + + @Test + fun `documentation with table`() { + testInline( + """ + |/src/main/java/sample/DocGenProcessor.java + |package sample; + |/** + | * <table> + | * <caption>List of supported types</caption> + | * <tr> + | * <td>cell 11</td> <td>cell 21</td> + | * </tr> + | * <tr> + | * <td>cell 12</td> <td>cell 22</td> + | * </tr> + | * </table> + | */ + | public class DocGenProcessor { } + """.trimIndent(), testConfiguration + ) { + pagesTransformationStage = { module -> + val classPage = + module.children.single { it.name == "sample" }.children.single { it.name == "DocGenProcessor" } as ContentPage + classPage.content.assertNode { + group { + header { +"DocGenProcessor" } + platformHinted { + group { + skipAllNotMatching() //Signature + } + comment { + table { + check { + caption!!.assertNode { + caption { + +"List of supported types" + } + } + } + group { + group { + +"cell 11" + } + group { + +"cell 21" + } + } + group { + group { + +"cell 12" + } + group { + +"cell 22" + } + } + } + } + } + } + skipAllNotMatching() + } + } + } + } + + + @Test fun `undocumented parameter and other tags`() { testInline( """ @@ -631,8 +1311,8 @@ class ContentForParamsTest : AbstractCoreTest() { } after { group { pWrapped("comment to function") } - unnamedTag("Author") { comment { +"Kordyjan" } } - unnamedTag("Since") { comment { +"0.11" } } + unnamedTag("Author") { comment { +"Kordyjan" } } + unnamedTag("Since") { comment { +"0.11" } } header(2) { +"Parameters" } group { diff --git a/plugins/base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt b/plugins/base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt index a2c45f63..4bc33c03 100644 --- a/plugins/base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt +++ b/plugins/base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt @@ -1,10 +1,12 @@ package content.seealso import matchers.content.* +import org.jetbrains.dokka.pages.ContentDRILink import org.jetbrains.dokka.pages.ContentPage import org.jetbrains.dokka.testApi.testRunner.AbstractCoreTest import org.junit.jupiter.api.Test import utils.* +import kotlin.test.assertEquals class ContentForSeeAlsoTest : AbstractCoreTest() { private val testConfiguration = dokkaConfiguration { @@ -207,8 +209,12 @@ class ContentForSeeAlsoTest : AbstractCoreTest() { platformHinted { table { group { - //DRI should be "kotlin.collections/Collection////" - link { +"Collection" } + link { + check { + assertEquals("kotlin.collections/Collection///PointingToDeclaration/", (this as ContentDRILink).address.toString()) + } + +"Collection" + } group { } } } diff --git a/plugins/base/src/test/kotlin/content/signatures/SkippingParenthesisForConstructorsTest.kt b/plugins/base/src/test/kotlin/content/signatures/SkippingParenthesisForConstructorsTest.kt index df1bfbc6..b09e5252 100644 --- a/plugins/base/src/test/kotlin/content/signatures/SkippingParenthesisForConstructorsTest.kt +++ b/plugins/base/src/test/kotlin/content/signatures/SkippingParenthesisForConstructorsTest.kt @@ -35,7 +35,7 @@ class ConstructorsSignaturesTest : AbstractCoreTest() { header(1) { +"SomeClass" } platformHinted { group { - +"class" + +"class " link { +"SomeClass" } } } @@ -65,7 +65,7 @@ class ConstructorsSignaturesTest : AbstractCoreTest() { header(1) { +"SomeClass" } platformHinted { group { - +"class" + +"class " link { +"SomeClass" } } } @@ -95,9 +95,9 @@ class ConstructorsSignaturesTest : AbstractCoreTest() { header(1) { +"SomeClass" } platformHinted { group { - +"class" + +"class " link { +"SomeClass" } - +"(a:" + +"(a: " group { link { +"String" } } +")" } @@ -128,9 +128,9 @@ class ConstructorsSignaturesTest : AbstractCoreTest() { header(1) { +"SomeClass" } platformHinted { group { - +"class" + +"class " link { +"SomeClass" } - +"(a:" // TODO: Make sure if we still do not want to have "val" here + +"(a: " // TODO: Make sure if we still do not want to have "val" here group { link { +"String" } } +")" } @@ -162,9 +162,9 @@ class ConstructorsSignaturesTest : AbstractCoreTest() { header(1) { +"SomeClass" } platformHinted { group { - +"class" + +"class " link { +"SomeClass" } - +"(a:" + +"(a: " group { link { +"String" } } +")" } @@ -213,9 +213,9 @@ class ConstructorsSignaturesTest : AbstractCoreTest() { header(1) { +"SomeClass" } platformHinted { group { - +"class" + +"class " link { +"SomeClass" } - +"(a:" + +"(a: " group { link { +"String" } } +")" } @@ -229,9 +229,9 @@ class ConstructorsSignaturesTest : AbstractCoreTest() { link { +"SomeClass" } platformHinted { group { - +"fun" + +"fun " link { +"SomeClass" } - +"(a:" + +"(a: " group { link { +"String" } } |