static-ier typed, questions in code comments

/*configurations {
  register("asciidoclet")
}*/

val asciiDoclet by configurations.registering // is this the same as above? I think so...

dependencies {
  asciiDoclet("org.asciidoctor:asciidoclet:2.+") // was "asciiDoclet"...
}


tasks.withType<Javadoc>().configureEach {
  dependsOn(tasks.classes) // optional: for annotation preprocessor generated code
  options {
    docletpath(*configurations.getByName("asciidoclet").files.toTypedArray()) // the registered thing doesn't return the same type as this, so files isn't there... what should I do?
//   probably not  docletpath(*asciiDoclet.map { it.files }.map { it.toTypedArray() }.get())

https://github.com/asciidoctor/asciidoclet/pull/143

// is this the same as above? I think so...

Besides this difference in the naming, yes

// optional: for annotation preprocessor generated code

Are you sure this is necessary? It if it is, are you sure those generated files are considered inputs, so is the task rerun if only those generated files change? Explicit

dependsOn

as always is a code smell, if the the first question is a yes and the second is a no, you probably instead need

inputs.files(...)

with the actual task creating the files instead.

probably not

As

docletpath

needs

File...

instances, I'd indeed say that is the proper solution. Well, I would put the

get()

first. No need to

map

if you anyway eagerly get it right away, so

docletpath(*asciiDoclet.get().files.toTypedArray())

// optional: for annotation preprocessor generated code

IIUC, generated sources won't be included in the default Javadoc sources, so this should rather be replaced with something like

source(sourceSets.main.map { it.output.generatedSourcesDirs })

(which will automatically bring a dependency on the

compileJava

task) Wrt

docletpath

, the method needs a

File...

but the property is a

List<File>

so you can chop off a

toTypedArray()

(but still need to eagerly resolve the configuration at configuration-time); hopefully something that will change to a

ConfigurableFileCollection

in Gradle 9.

> // optional: for annotation preprocessor generated code

Are you sure this is necessary?

It if it is, are you sure those generated files are considered inputs, so is the task rerun if only those generated files change?

not responding to thomas. I'm certain something like this is necessary if you have any sort of generated sources that might get referenced in your javadoc. We had this discussion a long time ago, and it was the only way I could get it to work. I might have to try what thomas is suggesting, I can't guarantee I haven't done that, but I know it's not correctly declared as an input. I recall trying many things. Now whether this is a good idea at all in this PR...

Wrt

docletpath

, the method needs a

File...

but the property is a

List<File>

so you can chop off a

toTypedArray()

thought I'd tried that...

I'm certain something like this is necessary if you have any sort of generated sources that might get referenced in your javadoc.

If the source generating task is properly defined as source directory, it should usually just work. But it might be that sources generated by the

JavaCompile

task through annotation processors might be special. 🤷‍♂️

yeah this has to be

toTypedArray()

, you have to glob an array to a varargs otherwise it would just get passed as the first element; because kotlin

What he means probably was doing instead

docletpath = asciiDoclet.get().files.toList()

.

If the source generating task is properly defined as source directory, it should usually just work.

it's not we discussed this months ago 😉 I guess you can source dive

What he means probably was doing instead

docletpath = asciiDoclet.get().files.toList()

.

ah, not certain if field assignment is more appropriate than calling the method... so I chose to use the provided abstraction

The abstraction level is the same. The difference is that

docletpath(...)

adds to the existing doclet path if any while

docletpath = ...

sets the doclet path to the given value.

right, but is that not a custom coded (meaning not generated) method? even if all it does is set, when they switch to Propertys that API doesn't have to change. That's what an abstraction is, meaning you can change the implementation without changing the abstraction. One of the problems I have with records and generating code from java property's (get/set) is that now because records decided that

id

means you get

id()

(honestly not even certain that is considred a property), that things that use

getId()

require an additional layer of abstraction, leaving me adding twice the methods just to support both... and silly default interfaces that have the method referencing the other method so I don't have to do it in every implementation. essentially the API's for these reflect their implementation and not an abstraction.