Clojurians Log v2

Also @corasaurus-hex is very often helpful with ui design trade-offs. She might, if she has time, chime in (absolutely no pressure Cora, I expect you are busy these days).

people come to docs to see what they can use and how they can use it and so deprecated is more important to know about than added. that said, it's not obvious how to get the right version of docs for a library (you click/tap the version at the top to pick different versions) and so looking at the latest docs it may be useful to see added. you won't also see "removed", though, so that's of limited utility

I think well-done UI can show added and not feel cluttered. we could also improve how versions are selected

there will always be a tension between what the cljdoc team thinks people need to see and what authors would like them to see, unfortunately. I like the idea of showing added, I sometimes find it helpful context, like a git blame but in the code

thanks @corasaurus-hex, much appreciated

we’ve been talking about semantic diffs (based on analysis data) and effectively using that to see changes between library versions.

don’t see anything wrong with supporting some representation of :added though

coolio, thanks @martinklepsch

Hi @serioga, cljdoc does not currently show added metadata, it does show deprecated metadata. It treats it as a boolean. Example:

But I have a memory of light grey ADDED label under function name...

Not sure, maybe it did once? Could you be thinking of some codox generated docs? https://weavejester.github.io/medley/medley.core.html#var-deep-merge:

Ah, maybe another documentation system...

Could be! My brain is foggy on this too. If cljdoc did start to show :added it would have to show the value, and for consistency, we'd like also show the value of :deprecated.

I'm pretty sure we collect and save :added during API analysis.

Given cljdoc's sparse design aesthetic, I'm guessing :added was omitted in the spirit avoiding visual clutter. But if it is considered generally useful info we should consider including it.

If author adds this information then author think that this info is useful :-)

Yep, all trade-offs ui minimalism vs info. For example the fact that a function is deprecated is more important than what version it was deprecated, hence cljdoc just showing "deprecated" (if I understand the design choice correctly). And deprecation is typically much more important to a user of a library than what version a var was added. I personally don't have a preference on this one. If @martinklepsch has a free moment, he might chime in.

I feel like you mean that ADDED conflicts with DEPRECATED but I don't understand why :-)

Deprecated is important, there is no standard for it's value afaik (but I would not mind see non-boolean value as well). Also it would be cool to show deprecated vars as striked-out in the sidebar's navigation (including namespaces).

> I feel like you mean that ADDED conflicts with DEPRECATED but I don't understand why :-) Nope, just trying to convey that DEPRECATED is probably more important information than ADDED for users of a library. > Also it would be cool to show deprecated vars as striked-out in the sidebar's navigation (including namespaces) Ya, I too was thinking some indication of deprecation would be nice in index views.