clj-commons / clj-commons/ordered
Consider defining the public API
- Dominant language
- Clojure
- Stars
- 267
- Forks
- 40
- Avg merge
- 14h 2m
- Merged PRs (30d)
- 17
Description
## Issue
While doing a cljdoc preview against master, I'm not clearly understanding what the supported public API is for `ordered`.
## A look at current API
Here's the current API with my interpretation (INTERNAL/PUBLIC)
- flatland.ordered.common [clj only]
- change! INTERNAL
- compact PUBLIC
- flatland.ordered.map [mix of clj and cljs]
- entry [clj] INTERNAL
- equiv-impl [cljs] INTERNAL
- ordered-map [clj/cljs] (but cljs is missing docstring) PUBLIC
- ordered-map-reader-clj [clj] INTERNAL
- ordered-map-reader-cljs [clj] INTERNAL
- print-ordered-map [cljs] INTERNAL
- transient-ordered-map [clj] INTERNAL
- flatland.ordered.set
- equiv-impl [cljs] INTERNAL
- hasheq-ordered-set [clj] INTERNAL
- into-ordered-set [clj/cljs] PUBLIC (for reader registration)
- into-ordered-set-reader-cljs [clj] INTERNAL
- ordered-set [clj/cljs] (but docstring differ, relevantly, but difference is hard to see) PUBLIC
- transient-ordered-set [clj] INTERNAL
As user will assume none of these are internal implementation details and might be confused what they should be using.
## User Guide
From the User Guide, we see the following in examples:
- flatland.ordered.set
- ordered-set
- into-ordered-set (to support runtime literals for cljs)
- flatland.ordered.map
- ordered-map
The User Guide also states that `flatland.ordered.common/compact` is JVM-only.
But nothing explains what it does.
## Proposal 1
Mark what seems INTERNAL with `no-doc` metadata.
Cljdoc will not include these items in its API docs.
(If we were starting today, I'd likely move internals to an impl namespace, but this is an old lib and folks are likely naively using internals.)
## Proposal 2
Always include a docstring on public API methods.
That means `into-ordered-set` and `compact` deserve docstrings.
## Proposal 3
Share docstrings and sigs for clj/cljs fns.
For example, this is awkward in cljdoc:
As is this:
If we were starting today, I'd propose using .cljc files.
But for now, copy and pasting between .clj and cljs with a reminder comment is good enough (it's not like we have a slew of fns!).
## Next Steps
Sound good? If so, I'm happy to proceed.
If not, happy to discuss.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the flatland.ordered.common, flatland.ordered.map, and flatland.ordered.set namespaces, then compare their public and internal functions with the User Guide examples. Review the clj and cljs docstrings and API listings; done means the supported API is clearly marked, public functions are documented consistently, and compact is explained.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- clojure
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100