Decouple is implemented using multiple design patt...

# decouple

[CLOVIS]

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

[Landry Norris]

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

[CLOVIS]

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.

[Landry Norris]

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.

[CLOVIS]

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).

[CLOVIS]

I'm not a fan of creating another documentation website just for this, I want users to be able to find everything (or almost everything) they're searching for directly in the Dokka website. Having multiple documentation websites always causes versioning issues, too. Maybe free-floating markdown files in the repo? That's the simplest, but it's not visible to downstream users (that's why I only used them for the FAQ and the contribution guide for now)

[molikuner]

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)

[Landry Norris]

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

[CLOVIS]

@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]

@Landry Norris the answer to that is still in the air. For now I haven't seen components with multiple completion events (regular events such as an input's onChange don't follow this pattern: they have no good reason to suspend). Worst case scenario, you always have the option to manually override the scope through coroutines:

val customScope = // custom scope

Foo(
  first = {
    // uses the default scope
  },
  second = {
    customScope.async {
      // forces the custom scope
    }.await()
  }
)

[CLOVIS]

So I think it's a good pattern to manage a default scope, allow the user to override it directly if needed, knowing that more complex cases can be handled by starting your own job from the event

[molikuner]

@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 🤔

[CLOVIS]

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

[molikuner]

I provided an implementation of eventHandler above 🤔

[CLOVIS]

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”

[msink]

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

[CLOVIS]

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

[David Herman]

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.

[CLOVIS]

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.