josdejong/mathjs

Documentation of Unit.format() is incomplete

Open

#3 440 ouverte le 28 mars 2025

Voir sur GitHub
 (3 commentaires) (2 réactions) (0 assignés)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.

Guide contributeur

Stack technique
javascript
Domaine
documentation
Type d'issue
documentation
DifficultéDifficulté estimée pour un nouveau contributeur, de 1 pour un très petit changement à 5 pour un travail expert.
2
Temps estiméFourchette de temps approximative pour investiguer, implémenter, tester et préparer une pull request.
1-3 hours
Statut d'activitéDisponibilité apparente de l'issue : fraîche, active, ancienne, bloquée ou en attente d'un mainteneur.
fresh
ClartéClarté avec laquelle l'issue explique le changement attendu, les critères d'acceptation et la prochaine étape.
clear
Prérequis
Aucun
Accessibilité débutantScore de 1 à 100 estimant l'accessibilité de cette issue pour un premier contributeur.
80
Direction de recherche
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.