Decouple is implemented using multiple design patterns that appear in a lot of components, but are not based on a class or another symbol that I could add documentation to. For example, components that can start an action have a suspending event and an optional coroutine scope that will by default cancel the action if the button goes offscreen (it is also possible to specify it explicitly). For example, a button looks like this:

@Composable
fun Button(
    …
    onClick: suspend () -> Unit,
    scope: CoroutineScope = rememberCoroutineScope(),
    …
)

This pattern is very convenient because it allows to use coroutines in all events, and it allows the button to automatically display a loading indicator if the event is taking too long. However, there is no good place to document it… I cannot copy-paste the documentation on each component that uses this pattern. I'm considering creating a

concepts

or

patterns

package in

core

that would only contain 'fake symbols' that can be documented. They would never be used in an actual application, but it would be easy to refer to them in documentation. For example, a dummy type alias:

/**
 * Explain the pattern here.
 */
typealias PatternName = Nothing // useless, takes no space in the final application

Do you think this approach is a good idea? 1️⃣ yes, using a

typealias = Nothing

(but typealiases do not get their own pages in Dokka, so it would be hard to link to them) 2️⃣ yes, using an empty

object

(but it will exist in the final binary) 3️⃣ no, use some kind of external documentation website (cannot see the explanation in the IntelliJ documentation popup, hard for users to know if the website matches the version of the library that they're using) 🔢 neutral

Would this not be part of the KDoc? If I saw a coroutine scope as a parameter, I’d generally expect to see a note on what the parameter is for. Maybe something as simple as

scope to run onClick. By default, it is cancelled when the view leaves the screen

I guess it could be. I would like to have a centralized place where all patterns are documented, preferably visible in the Dokka output and easy to navigate to in IDEA for a downstream user. Indeed in this case, maybe copy-pasting that sentence to all components would do the job.

I like to keep a docs folder with Markdown files for complex projects. Not sure if dokka has a way to import additional Markdown files yet.

Sadly, Dokka can only import markdown package/module headers, but they cannot create their own pages. You may have already seen it but I experimented with having a separate module just for documentation to add it in the Dokka output (https://opensavvy.gitlab.io/decouple/documentation/documentation/explanations/-component%20variants/index.html), it looks good but other modules cannot refer to it (though it can refer to other modules).

How about introducing something like this:

/**
 * Your documentation here
 */
data class EventHandler(val handler: suspend () -> Unit, val scope: CoroutineScope)

/**
 * Your other documentation here
 */
@Compose
fun eventHandler(scope: CoroutineScope = remeberCoroutineScope(), handler: suspend () -> Unit) = EventHandler(handler, scope)

While this introduces an extra allocation, Compose might be able to optimize it, if you annotate the class with

@Stable

or so. Once muti-value inline classes land you might even be able to inline it again 🤔😄 (I've typed this in Slack, so no idea whether this actually works)

what happens if the user provides a different scope for several handlers? Is that desired?

@molikuner the problem with that approach is that you're locked into the event being

() -> Unit

. That's fine for a button, but maybe some other component may have a different signature, or even return a value. It's also very inconvenient to call, you've gone from

Button(onClick = {...}) {...}

to

Button(onClick = EventHandler(rememberCoroutineScope()) {...}) {...}

which is less than ideal. In any case, my only issue with the current signature is that it's hard to document, which IMO is not worth actually changing it (the most important part is that it's easy to use and easy to read).

@CLOVIS the call Syntax wouldn't be that bad:

Button(onClick = eventHandler { ... }) { ... }

And the issue about different types could be fixed using generics and overloading, but it's more boilerplate for the library for sure 🤔

It would be that bad... rememberCoroutineScope is Composable, you can only use it as a default value in a Composable function (and the event constructor isn't) Unless

eventHandler

becomes an inline Composable factory, but that's even harder to read for a new user or maintain

I provided an implementation of

eventHandler

above 🤔

Ah sorry, I missed it. You're right, it would work, but I think it's too complicated. I want components to be as similar as possible to regular Compose components, and currently if you exclude optional parameters, the only difference you'll see is “ah, I can suspend in onClick”

Use preprocessor for KDoc? https://github.com/Jolanrensen/docProcessorGradlePlugin

That's very interesting. The author seems to say it's not ready for usage, but I'm especially interested because from what I understand, library maintainers see the unexpanded comments, but library users see the expanded comments when using the IDE

At some point, you're probably going to want to create a demo project to show off Decouple. I know you don't want an external docs site, but one possibility is your external docs site is the Decouple demo project which could kill two birds with one stone.

Yes, that's the plan. I was just planning to use it as a helper for designers, but you're right that it's a great place to put architectural information.