clj-commons / clj-commons/ordered

Consider defining the public API

Open
#98 2 comments 0 reactions 0 assignees View on GitHub
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:

Image

As is this:

Image

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.