Declare public symbols

[Eben60]

Declaration of public symbols as requested in #749

Notes:

• I had no idea which symbols maintainers would like to declare as public, thus tried my best guess.
• Variable names starting with underscore considered private.
• The file public.julia lists non-public symbols, too. That is for maintainers to have an overview, can be removed later, of course.
• The file public.julia has non-standard suffix because I remember having some issues with .jl suffix in such a case. It could be CodeCov, not sure. Can be changed to .jl if desired.
• See https://github.com/Eben60/Unitful.jl/blob/list_pub_symbols/docs/public_listing.jl to see how the file public.julia was generated.
• I've created a testset to check if all variables are declared in one way or another. This testset is put it to the top of runtest.jl because I got errors elswhere (see below).
• Declaring VelocityFreeUnits as public (or exported, for that case) leads to failure of the "Display" testset. No idea why, but reproduced on Mac and Ubuntu. For debugging, see https://github.com/Eben60/Unitful.jl/tree/mark_public_units_debug

[codecov]

Codecov Report

❌ Patch coverage is 67.56757% with 12 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (master@2eba283). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/user.jl	71.42%	8 Missing ⚠️
src/pkgdefaults.jl	60.00%	2 Missing ⚠️
src/utils.jl	50.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #811   +/-   ##
=========================================
  Coverage          ?   88.90%           
=========================================
  Files             ?       21           
  Lines             ?     1722           
  Branches          ?        0           
=========================================
  Hits              ?     1531           
  Misses            ?      191           
  Partials          ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[giordano]

1. Why .julia extension instead of .jl?
2. This file is simply unmaintainable. Adding an option to macros like @unit/@dimension/@derived_dimension to make the symbol public looks a much more sustainable solution going forward

[Eben60]

Adding an option to macros

I agree, and would look into a macro solution.

Independent on that: Before I continue, I'd prefer to know whether the the variables sorting into private and public, as currently implemented in public.julia is OK, or needs any changes.

May I ask the maintainers to have a look?

[sostock]

I would declare the following as public:

• all physical constants,
• everything defined through @dimension/@derived_dimension,
• AbstractQuantity,
• all non-logarithmic units (most of them are defined through @refunit/@unit, but some, like ha and Å, will have to be treated manually). For @affineunit, adding an extra argument to the macro has less of an advantage, since it only defines one symbol, but it could be done just to be consistent with @refunit/@unit.

Those are all the symbols I would declare public right now. Others can be added later.

I’m not sure about the logarithmic units. I wouldn’t declare them public for now, since I consider them broken in a way that cannot be fixed without major (and breaking) changes, but on the other hand, they can be accesssed through u"…" and are widely used (I think).

[Eben60]

@sostock On log units: They are intended for the package user, not for some internal purposes. Therefore IMO they should be declared public, too. I'd suggest adding a warning to the docstrings about their experimental nature.

[Eben60]

Another question: @dimension returns the dimension, @unit returns the unit, whereas @derived_dimension returns nothing. If that is intended, what's the reason? Otherwise I'd change @derived_dimension to return the dimension, too

[sostock]

@dimension 𝐋 "𝐋" Length true returns Unitful.𝐋 (not Unitful.Length), so if @derived_dimension Area 𝐋^2 true returned something, it should return 𝐋^2, anything else would be inconsistent. But the value 𝐋^2 is not bound to any symbol by the macro, so I can see why there is no use in returning it.

[Eben60]

@sostock

everything defined through @dimension/@derived_dimension

Each @dimension defines four bindings, eg. for Lenth we create and declare as public
𝐋, Length, LengthUnits, LengthFreeUnits. My current macro implementation makes all them public - but I'm not sure it is what you meant, or was it just the first two of them.

[sostock]

My current macro implementation makes all them public

That’s what I would do as well.

[sostock]

I haven’t reviewed the code yet, these comments are just about the default value of the new argument and the docstrings.

[sostock]

Is there a reason why the new macro argument isn’t used here?

[Eben60]

changed to use macro argument

[Eben60]

I'd also suggest to declare DefaultSymbols as public and attach docstring to it. @sostock should I?