https://kotlinlang.org logo
Channels
100daysofcode
100daysofkotlin
100daysofkotlin-2021
advent-of-code
aem
ai
alexa
algeria
algolialibraries
amsterdam
android
android-architecture
android-databinding
android-studio
androidgithubprojects
androidthings
androidx
androidx-xprocessing
anime
anko
announcements
apollo-kotlin
appintro
arabic
argentina
arkenv
arksemdevteam
armenia
arrow
arrow-contributors
arrow-meta
ass
atlanta
atm17
atrium
austin
australia
austria
awesome-kotlin
ballast
bangladesh
barcelona
bayarea
bazel
beepiz-libraries
belgium
benchmarks
berlin
big-data
books
boston
brazil
brikk
budapest
build
build-tools
bulgaria
bydgoszcz
cambodia
canada
carrat
carrat-dev
carrat-feed
chicago
chile
china
chucker
cincinnati-user-group
cli
clikt
cloudfoundry
cn
cobalt
code-coverage
codeforces
codemash-precompiler
codereview
codingame
codingconventions
coimbatore
collaborations
colombia
colorado
communities
competitive-programming
competitivecoding
compiler
compose
compose-android
compose-desktop
compose-hiring
compose-ios
compose-mp
compose-ui-showcase
compose-wear
compose-web
confetti
connect-audit-events
corda
cork
coroutines
couchbase
coursera
croatia
cryptography
cscenter-course-2016
cucumber-bdd
cyprus
czech
dagger
data2viz
databinding
datascience
dckotlin
debugging
decompose
decouple
denmark
deprecated
detekt
detekt-hint
dev-core
dfw
docs-revamped
dokka
domain-driven-design
doodle
dsl
dublin
dutch
eap
eclipse
ecuador
edinburgh
education
effective-kotlin
effectivekotlin
emacs
embedded-kotlin
estatik
event21-community-content
events
exposed
failgood
fb-internal-demo
feed
firebase
flow
fluid-libraries
forkhandles
forum
fosdem
fp-in-kotlin
framework-elide
freenode
french
fritz2
fuchsia
functional
funktionale
gamedev
ge-kotlin
general-advice
georgia
geospatial
german-lang
getting-started
github-workflows-kt
glance
godot-kotlin
google-io
gradle
graphic
graphkool
graphql
graphql-kotlin
graviton-browser
greece
grpc
gsoc
gui
hackathons
hacktoberfest
hamburg
hamkrest
helios
helsinki
hexagon
hibernate
hikari-cp
hire-me
hiring
hiring-french
hongkong
hoplite
http4k
hungary
hyderabad
image-processing
india
indonesia
inkremental
intellij
intellij-plugins
intellij-tricks
internships
introduce-yourself
io
ios
iran
israel
istanbulcoders
italian
jackson-kotlin
jadx
japanese
jasync-sql
java-to-kotlin-refactoring
javadevelopers
javafx
javalin
javascript
jdbi
jhipster-kotlin
jobsworldwide
jpa
jshdq
juul-libraries
jvm-ir-backend-feedback
jxadapter
k2-early-adopters
kaal
kafka
kakao
kalasim
kapt
karachi
karg
karlsruhe
kash_shell
kaskade
kbuild
kdbc
kgen-doc-tools
kgraphql
kinta
klaxon
klock
kloudformation
kmdc
kmm-español
kmongo
knbt
knote
koalaql
koans
kobalt
kobweb
kodein
kodex
kohesive
koin
koin-dev
komapper
kondor-json
kong
kontent
kontributors
korau
korean
korge
korim
korio
korlibs
korte
kotest
kotest-contributors
kotless
kotlick
kotlin-asia
kotlin-beam
kotlin-by-example
kotlin-csv
kotlin-data-storage
kotlin-foundation
kotlin-fuel
kotlin-in-action
kotlin-inject
kotlin-latam
kotlin-logging
kotlin-multiplatform-contest
kotlin-mumbai
kotlin-native
kotlin-pakistan
kotlin-plugin
kotlin-pune
kotlin-roadmap
kotlin-samples
kotlin-sap
kotlin-serbia
kotlin-spark
kotlin-szeged
kotlin-website
kotlinacademy
kotlinbot
kotlinconf
kotlindl
kotlinforbeginners
kotlingforbeginners
kotlinlondon
kotlinmad
kotlinprogrammers
kotlinsu
kotlintest
kotlintest-devs
kotlintlv
kotlinultimatechallenge
kotlinx-datetime
kotlinx-files
kotlinx-html
kotrix
kotson
kovenant
kprompt
kraph
krawler
kroto-plus
ksp
ktcc
ktfmt
ktlint
ktor
ktp
kubed
kug-leads
kug-torino
kvision
kweb
lambdaworld_cadiz
lanark
language-evolution
language-proposals
latvia
leakcanary
leedskotlinusergroup
lets-have-fun
libgdx
libkgd
library-development
lincheck
linkeddata
lithuania
london
losangeles
lottie
love
lychee
macedonia
machinelearningbawas
madrid
malaysia
mathematics
meetkotlin
memes
meta
metro-detroit
mexico
miami
micronaut
minnesota
minutest
mirror
mockk
moko
moldova
monsterpuzzle
montreal
moonbean
morocco
motionlayout
mpapt
mu
multiplatform
mumbai
munich
mvikotlin
mvrx
myndocs-oauth2-server
naming
navigation-architecture-component
nepal
new-mexico
new-zealand
newname
nigeria
nodejs
norway
npm-publish
nyc
oceania
ohio-kotlin-users
oldenburg
oolong
opensource
orbit-mvi
osgi
otpisani
package-search
pakistan
panamá
pattern-matching
pbandk
pdx
peru
philippines
phoenix
pinoy
pocketgitclient
polish
popkorn
portugal
practical-functional-programming
proguard
prozis-android-backup
pyhsikal
python
python-contributors
quasar
random
re
react
reaktive
realm
realworldkotlin
reductor
reduks
redux
redux-kotlin
refactoring-to-kotlin
reflect
refreshversions
reports
result
rethink
revolver
rhein-main
rocksdb
romania
room
rpi-pico
rsocket
russian
russian_feed
russian-kotlinasfirst
rx
rxjava
san-diego
science
scotland
scrcast
scrimage
script
scripting
seattle
serialization
server
sg-user-group
singapore
skia-wasm-interop-temp
skrape-it
slovak
snake
sofl-user-group
southafrica
spacemacs
spain
spanish
speaking
spek
spin
splitties
spotify-mobius
spring
spring-security
squarelibraries
stackoverflow
stacks
stayhungrystayfoolish
stdlib
stlouis
strife-discord-lib
strikt
students
stuttgart
sudan
swagger-gradle-codegen
swarm
sweden
swing
swiss-user-group
switzerland
talking-kotlin
tallinn
tampa
teamcity
tegal
tempe
tensorflow
terminal
test
testing
testtestest
texas
tgbotapi
thailand
tornadofx
touchlab-tools
training
tricity-kotlin-user-group
trójmiasto
truth
tunisia
turkey
turkiye
twitter-feed
uae
udacityindia
uk
ukrainian
uniflow
unkonf
uruguay
utah
uuid
vancouver
vankotlin
vertx
videos
vienna
vietnam
vim
vkug
vuejs
web-mpp
webassembly
webrtc
wimix_sentry
wwdc
zircon
Powered by
Title
c

CLOVIS

03/01/2023, 5:19 PM
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
l

Landry Norris

03/01/2023, 5:27 PM
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
c

CLOVIS

03/01/2023, 5:29 PM
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.
l

Landry Norris

03/01/2023, 5:31 PM
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.
c

CLOVIS

03/01/2023, 5:34 PM
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).
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)
m

molikuner

03/01/2023, 5:59 PM
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)
l

Landry Norris

03/01/2023, 6:00 PM
what happens if the user provides a different scope for several handlers? Is that desired?
c

CLOVIS

03/01/2023, 7:15 PM
@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).
@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()
  }
)
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
m

molikuner

03/01/2023, 7:25 PM
@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 🤔
c

CLOVIS

03/01/2023, 7:26 PM
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
m

molikuner

03/01/2023, 7:28 PM
I provided an implementation of
eventHandler
above 🤔
c

CLOVIS

03/01/2023, 7:30 PM
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”
m

msink

03/01/2023, 7:55 PM
c

CLOVIS

03/01/2023, 8:03 PM
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
d

David Herman

03/05/2023, 4:14 PM
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.
c

CLOVIS

03/05/2023, 6:50 PM
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.