Add docstring for Tar module

[lgoettgens]

Handles the Tar part of JuliaLang/julia#52725.

cc @stevengj

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (166deb3) 97.53% compared to head (0b29591) 97.53%.
Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #173   +/-   ##
=======================================
  Coverage   97.53%   97.53%           
=======================================
  Files           4        4           
  Lines         810      810           
=======================================
  Hits          790      790           
  Misses         20       20           

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

[stevengj]

I notice that none of these functions are currently exported. In Julia 1.11, they should be declared public, e.g. something like the following to src/Tar.jl:

if VERSION >= v"1.11" # declare public, non-exported API
    eval(Meta.parse("public create, extract, list, rewrite, tree_hash, Header"))
end

since this is apparently the documented API.

I'm not sure if there is a way to avoid eval(Meta.parse(...)) since the public keyword does not parse in earlier Julia versions?

(Otherwise, these symbols aren't included in names(Tar), so their docstrings aren't even being checked by the test below.)

[lgoettgens]

I think this is out of scope of this PR. I'll reference it in JuliaLang/julia#51335 instead to not forget.

[LilithHafner]

I'm not sure if there is a way to avoid eval(Meta.parse(...)) since the public keyword does not parse in earlier Julia versions?

The only good way to avoid that that I know of is to use Compat.jl's @compat public foo, bar, though this is a fine use of eval(Meta.parse(....)) imo.

[vtjnash]

Or make a small macro here macro public(v); @assert isexpr(v, :tuple); VERSION ? esc(Expr(:public, v.args...)); nothing; end so that it just needs to add an @ to make it syntactically valid here

[LilithHafner]

That macro (with some bug-fixes) is here https://github.com/JuliaLang/Compat.jl/pull/805/files/0c90fae7a869a5f526a4cb13620ea077fc30456e, though it was renamed to @compat public.

[lgoettgens]

Can we get this PR here merged? The discussion about declaring public symbols can be moved to #174 and/or #175. There I already implemented two different approaches

[LilithHafner]

LGTM

@stevengj, is there anything you're waiting for before merge