josdejong/mathjs

Documentation of Unit.format() is incomplete

Open

#3440 opened on Mar 28, 2025

View on GitHub
 (3 comments) (2 reactions) (0 assignees)JavaScript (13,832 stars) (1,298 forks)batch import
category:unitsdocumentationgood first issue

Description

Describe the bug The documentation at https://mathjs.org/docs/datatypes/units.html just says "The function will determine the best fitting prefix for the unit", and the Class page at https://mathjs.org/docs/reference/classes/unit.html. One place or the other should provide detail on how the best prefix is selecting, documenting the bias toward the current unit, and the preference for a larger number of tenths over a large number of hundreds (which not everyone may agree with). The absence of such documentation leads to concerns such as #3430.

Contributor guide

Tech stack
javascript
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
None
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80
Research direction
The issue requests better documentation for the Unit.format() method. Start by examining the current documentation files at https://mathjs.org/docs/datatypes/units.html and the source code for format() in the mathjs repository to understand the algorithm for selecting the best prefix. Look at the algorithm's logic, especially the bias toward the current unit and preference for larger number of tenths. Then update the documentation to describe this behavior clearly. The existing comments in issue #3430 may provide additional insight.