jolanrensen / docprocessorgradleplugin Goto Github PK

Gradle Plugin: KDoc / JavaDoc Preprocessor that can produce modified sources

License: MIT License

Kotlin 100.00%

gradle gradle-plugin java kotlin kdoc documentation documentation-generator documentation-tool javadoc javadocs kdocs library library-management plugin plugins preprocessor preprocessors

docprocessorgradleplugin's Issues

Expanding Java {@link ReferenceLinks}

Currently only Kotlin references are recognized and expanded to their full path when copied using @include or when used as key in @arg/@includeArg. Java link statements are more difficult to support since they are more complex, but they can still be supported if there exists a need for it.

Make @delete processor

..that would remove any definition it's used on. Currently, the interfaces used only for docs clog the sources.jar.

Dokka 1.9.10

Need to update to 1.9.10

Take HTML tags into account when breaking up documentation by tags or tag arguments.

Currently, only the following characters are taken into account when splitting up tag arguments or docs: {}, [], (), <>, `, ", ', '''.
Html tags are also supported in JavaDoc and MarkDown but are ignored for now.

`splitDocContentPerBlock()`'s block detection is inconsistent with KDoc

currently, doc like

/**
 * @a {
 * @b}
 * @c
 */

is broken up like ["@a {\n@b}", "@c"]. This is helpful if inline tags cross multiple lines, but I think it may be better to honor the actual KDoc rule of "starting a line with @tag creates a block", making it split up like ["@a {", "@b}", "@c"].

References to extension/member functions that exist in a supertype don't work

given

public interface ColumnWithPath<out T> : DataColumn<T> {}

public fun <T> DataColumn<T>.any(predicate: Predicate<T>)

/**
 * [ColumnWithPath.any]
 */

IntelliJ can link this reference up fine, but the plugin cannot.

Move removing '\' to its own processor

Makes it so "\}" notations etc. aren't necessary anymore.

This is dependent on splitDocContentPerBlock() to work correctly #31

IncludeFileDocProcessor: Figure out how to make file location clickable (if ever possible)

Currently in KDocs only http(s) urls are clickable in KDocs, like: [test](https://google.com). It would be very useful and safe to be able to click on a file URL that opens the file in the IDE.

I mentioned it here https://youtrack.jetbrains.com/issue/KTIJ-24290/Improve-KDoc-experience

Separate Dokka from Doc Processors so they can run and be tested more easily

Currently, doc processors can only be run and tested in a full gradle project with access to Dokka Documentables that cannot (easily) be mocked.
This also limits the processors to only being run in this environment and not in, potentially, other ones (such as an IntelliJ plugin).

Support read-only docs

Such as docs from libraries, perhaps type aliases etc.

Type Alias support

Might be a Dokka limitation, but currently DTypeAlias is not a WithSource, so no DocumentableWithSources can be created for it. Explore if we can still access its docs and/or modify them.

Maybe relevant: #13

Use Konsist instead of Dokka for file analysis from Gradle

https://github.com/LemonAppDev/konsist

I've been unable to update Dokka past v1.8.10, since they've been closing off parts of their analysis API. Maybe Konsist could provide a new approach

Performance

Running the processor with Gradle can take a long while in a project the size of DataFrame. This can be felt most using the @include and arg processors, mainly, probably, because they're used the most in the project.

Some performance steps need to be researched.

Rendering sometimes breaks with `[]`

`df.`[select][DataFrame.select]` { `[colsOf][colsOf]`<`[String][String]`>()`[`[`][cols]`1, 3, 5`]` }`

{@includeArg something}

works but

`df.`[select][DataFrame.select]` { `[colsOf][colsOf]`<`[String][String]`>()`[`[`][cols]`1, 3, 5`[`]`][cols]` }`

{@includeArg something}

does not.

The includeArg does not get rendered because it probably thinks it's still in a code block or something.

Custom preprocessors currently don't work

Adding a dependency on a created plugin results in an exception:

java.lang.AbstractMethodError: org.jetbrains.dokka.analysis.AnalysisEnvironment$createResolutionFacade$library$1.getCapabilities()Ljava/util/Map;
	at org.jetbrains.kotlin.analyzer.AbstractResolverForProject.createModuleDescriptor(AbstractResolverForProject.kt:207)
	at org.jetbrains.kotlin.analyzer.AbstractResolverForProject.access$createModuleDescriptor(AbstractResolverForProject.kt:17)
	at org.jetbrains.kotlin.analyzer.AbstractResolverForProject$doGetDescriptorForModule$1.invoke(AbstractResolverForProject.kt:175)
	at org.jetbrains.kotlin.analyzer.AbstractResolverForProject$doGetDescriptorForModule$1.invoke(AbstractResolverForProject.kt:173)
	at org.jetbrains.kotlin.storage.LockBasedStorageManager.compute(LockBasedStorageManager.java:290)
	at org.jetbrains.kotlin.analyzer.AbstractResolverForProject.doGetDescriptorForModule(AbstractResolverForProject.kt:173)
	at org.jetbrains.kotlin.analyzer.AbstractResolverForProject.descriptorForModule(AbstractResolverForProject.kt:150)
	at org.jetbrains.kotlin.analyzer.AbstractResolverForProject.descriptorForModule(AbstractResolverForProject.kt:17)
	at org.jetbrains.dokka.analysis.AnalysisEnvironment.createResolutionFacade(AnalysisEnvironment.kt:272)
	at org.jetbrains.dokka.analysis.AnalysisContextKt.createAnalysisContext(AnalysisContext.kt:51)
	at org.jetbrains.dokka.analysis.AnalysisContextKt.createAnalysisContext(AnalysisContext.kt:24)
	at org.jetbrains.dokka.analysis.KotlinAnalysisKt.ProjectKotlinAnalysis(KotlinAnalysis.kt:18)
	at org.jetbrains.dokka.analysis.KotlinAnalysisKt.ProjectKotlinAnalysis$default(KotlinAnalysis.kt:15)
	at org.jetbrains.dokka.base.DokkaBase$defaultKotlinAnalysis$2$1.invoke(DokkaBase.kt:194)
	at org.jetbrains.dokka.base.DokkaBase$defaultKotlinAnalysis$2$1.invoke(DokkaBase.kt:47)
	at org.jetbrains.dokka.plugability.LazyEvaluated.get$core(LazyEvaluated.kt:8)
	at org.jetbrains.dokka.plugability.DokkaContextConfigurationImpl.single(DokkaContext.kt:159)
	at org.jetbrains.dokka.base.translators.psi.DefaultPsiToDocumentableTranslator.<init>(DefaultPsiToDocumentableTranslator.kt:867)
	at org.jetbrains.dokka.base.DokkaBase$psiToDocumentableTranslator$2$1.invoke(DokkaBase.kt:74)
	at org.jetbrains.dokka.base.DokkaBase$psiToDocumentableTranslator$2$1.invoke(DokkaBase.kt:47)
	at org.jetbrains.dokka.plugability.LazyEvaluated.get$core(LazyEvaluated.kt:8)
	at org.jetbrains.dokka.plugability.DokkaContextConfigurationImpl.actions(DokkaContext.kt:164)
	at org.jetbrains.dokka.plugability.DokkaContextConfigurationImpl.get(DokkaContext.kt:147)
	at nl.jolanrensen.docProcessor.ProcessDocsAction.analyseSourcesWithDokka(ProcessDocsAction.kt:99)
	at nl.jolanrensen.docProcessor.ProcessDocsAction.process(ProcessDocsAction.kt:48)
	at nl.jolanrensen.docProcessor.gradle.ProcessDocsGradleAction.execute(ProcessDocsGradleAction.kt:30)
	at org.gradle.workers.internal.DefaultWorkerServer.execute(DefaultWorkerServer.java:63)
	at org.gradle.workers.internal.AbstractClassLoaderWorker$1.create(AbstractClassLoaderWorker.java:49)
	at org.gradle.workers.internal.AbstractClassLoaderWorker$1.create(AbstractClassLoaderWorker.java:43)
	at org.gradle.internal.classloader.ClassLoaderUtils.executeInClassloader(ClassLoaderUtils.java:97)
	at org.gradle.workers.internal.AbstractClassLoaderWorker.executeInClassLoader(AbstractClassLoaderWorker.java:43)
	at org.gradle.workers.internal.IsolatedClassloaderWorker.run(IsolatedClassloaderWorker.java:49)
	at org.gradle.workers.internal.IsolatedClassloaderWorker.run(IsolatedClassloaderWorker.java:30)
	at org.gradle.workers.internal.IsolatedClassloaderWorkerFactory$1.lambda$execute$0(IsolatedClassloaderWorkerFactory.java:57)
	at org.gradle.workers.internal.AbstractWorker$1.call(AbstractWorker.java:44)
	at org.gradle.workers.internal.AbstractWorker$1.call(AbstractWorker.java:41)
	at org.gradle.internal.operations.DefaultBuildOperationRunner$CallableBuildOperationWorker.execute(DefaultBuildOperationRunner.java:204)
	at org.gradle.internal.operations.DefaultBuildOperationRunner$CallableBuildOperationWorker.execute(DefaultBuildOperationRunner.java:199)
	at org.gradle.internal.operations.DefaultBuildOperationRunner$2.execute(DefaultBuildOperationRunner.java:66)
	at org.gradle.internal.operations.DefaultBuildOperationRunner$2.execute(DefaultBuildOperationRunner.java:59)
	at org.gradle.internal.operations.DefaultBuildOperationRunner.execute(DefaultBuildOperationRunner.java:157)
	at org.gradle.internal.operations.DefaultBuildOperationRunner.execute(DefaultBuildOperationRunner.java:59)
	at org.gradle.internal.operations.DefaultBuildOperationRunner.call(DefaultBuildOperationRunner.java:53)
	at org.gradle.internal.operations.DefaultBuildOperationExecutor.call(DefaultBuildOperationExecutor.java:73)
	at org.gradle.workers.internal.AbstractWorker.executeWrappedInBuildOperation(AbstractWorker.java:41)
	at org.gradle.workers.internal.IsolatedClassloaderWorkerFactory$1.execute(IsolatedClassloaderWorkerFactory.java:49)
	at org.gradle.workers.internal.DefaultWorkerExecutor.lambda$submitWork$2(DefaultWorkerExecutor.java:205)
	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
	at org.gradle.internal.work.DefaultConditionalExecutionQueue$ExecutionRunner.runExecution(DefaultConditionalExecutionQueue.java:187)
	at org.gradle.internal.work.DefaultConditionalExecutionQueue$ExecutionRunner.access$700(DefaultConditionalExecutionQueue.java:120)
	at org.gradle.internal.work.DefaultConditionalExecutionQueue$ExecutionRunner$1.run(DefaultConditionalExecutionQueue.java:162)
	at org.gradle.internal.Factories$1.create(Factories.java:31)
	at org.gradle.internal.work.DefaultWorkerLeaseService.withLocks(DefaultWorkerLeaseService.java:270)
	at org.gradle.internal.work.DefaultWorkerLeaseService.runAsWorkerThread(DefaultWorkerLeaseService.java:119)
	at org.gradle.internal.work.DefaultWorkerLeaseService.runAsWorkerThread(DefaultWorkerLeaseService.java:124)
	at org.gradle.internal.work.DefaultConditionalExecutionQueue$ExecutionRunner.runBatch(DefaultConditionalExecutionQueue.java:157)
	at org.gradle.internal.work.DefaultConditionalExecutionQueue$ExecutionRunner.run(DefaultConditionalExecutionQueue.java:126)
	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
	at org.gradle.internal.concurrent.ExecutorPolicy$CatchAndRecordFailures.onExecute(ExecutorPolicy.java:64)
	at org.gradle.internal.concurrent.ManagedExecutorImpl$1.run(ManagedExecutorImpl.java:48)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
	at java.lang.Thread.run(Thread.java:750)

Plugin breaks if no package is defined at the top of the file

Add @tags to autocomplete recommendation in IntelliJ plugin

Using multiple @sample block tags after each other makes repetition happen

for instance:

/**
 * First sample:
 * @sample [someSample]
 *
 * {@sampleNoComments [someSample]}
 *
 * Second sample:
 * {@sample [someOtherSample]}
 *
 * Java sample:
 * @sample JavaClass.javaMethod
 */

Windows and MacOS failures

java.lang.IllegalArgumentException: Could not find end of comment.
    Paths: [org.jetbrains.kotlinx.dataframe.api.fillNulls, org.jetbrains.kotlinx.dataframe.DataFrame.fillNulls]
    Comment Content: "null"
    Query: "e interface CommonFillNullsFunctionDoc
    
    /**
     * @include [CommonFillNullsFunctionDoc]
     * @include [SelectingColumns.Dsl.WithExample] {@include [SetFillNullsOper"

Filtering in the file
Optional addition of HTML tags (for JavaDocs) or triple quotes (for KDocs)

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.