https://kotlinlang.org logo
Join Slack
Powered by
Just learned about explicit api mode. Seems like a...
# library-development
c
Just learned about explicit api mode. Seems like a no brainer for every library to enable that flag. Am I wrong in thinking that? Do you enable explicitApi mode?
no red 4
👌 16
I also wonder if there's a way to fail if no docs for a public method 😅
h
You can enable a warning in dokka, but I don’t know if you can create an error.
m
I don't find it useful personally. It fragments the language and I need to track public API with a tool like BCV anyways
c
I very much dislike the mandatory 
public
, so I don't enable it. However, I would like to enable "all public symbols must have an explicit type", but that can't be enabled by itself AFAIK.
➕ 3
r
I seem to be a in a small minority in actually liking java's default of non-public visibility, it's much harder to accidentally expose something you didn't mean to. I often find that the build health plugin is telling me that something has suddenly become an api dependency of a module, and it turns out it's just that someone forgot to put 
internal
somewhere they should have.
c
In theory, I would prefer if the default was 
internal
for library authors. However, in practice, I don't really make that mistake, so I'd rather keep everything simple to read. We can already combine quite a few modifiers, an optional one is welcome IMO
m
@Rob Elliot you are not alone, there's a long thread in the Kotlin forums about this
r
Reading those, I'm struck that one of my strong beliefs after 25 years doing this job is that "application writers" should really be writing a lot of libraries with a very thin layer of application code at the top. My application's gradle structure has a tiny app module and then tons of other modules that are effectively libraries. It's in that context I want to control coupling between those modules by minimising visibility. (It would be nice to be able to do this easier without doing it at the gradle level, but that's another story entirely...)
💯 4
r
I've generally been a fan of explicitApi, but as BCV matures I agree it gets a little less necessary. Still, I think I personally don't mind a little bit more method header clutter in exchange for being explicit. Type inference is nice but I find it useful when looking through the source of a library I'm calling into to be able to tell at-a-glance what functions are available to call into and what types they return.
👍 1
c
BCV is Binary Compatibility Validator that's currently experimental right?
m
The KGP api is experimental
But using it is better than not using it
You can also look into Google metalava for alternatives
c
TIL of metalava. will look into it. strange crazy world of library development. 😂
😄 1
e
@CLOVIS problem is that the approach of not making mistakes scales poorly. At least for open source, my experience is that new contributors don't consider API visibility when adding code
b
🤫 
-XXexplicit-return-types=strict
👀 3
❗ 3
m
@Emil Kantis if you add BCV to your CI checks, there is no other way than considering visibility
mandalorian 1
c
@bnorm Ohhh, that's very interesting! Does it make them mandatory for all members, or only public members? If it's only public members, I'm going to enable this on all my projects this week 😅
b
From the CLI argument definition:
```Force the compiler to report errors on all public API declarations without an explicit return type.
Use the 'warning' level to issue warnings instead of errors.
This flag partially enables functionality of 
-Xexplicit-api
flag, so please don't use them altogether```
c
Thanks, that's perfect. I didn't know where the find the flag documentation, that's a useful file 🙏
Oh, that reminds me I have to enable the value checker too.
j
We've been doing our libraries without for years, and only recently now that we're preparing for a big publicity push started updating to explicit API. After a bit of using it, I highly recommend it for libraries. The requirement to consciously decide what to expose is important for external use.
➕ 2
Open in Slack
Previous
Powered by