Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docstring for Tar module #173

Merged
merged 3 commits into from
Feb 9, 2024
Merged

Add docstring for Tar module #173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
37752ab
Add docstring for Tar module
lgoettgens Feb 6, 2024
d655c20
Add docstring test
lgoettgens Feb 6, 2024
0b29591
Apply suggestions from code review
lgoettgens Feb 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/src/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
EditURL = "https://github.com/JuliaIO/Tar.jl/blob/master/docs/src/index.md"
```

The `Tar` module provides a simple interface for handling tar archives, including creation of
archives, extraction of selected files from an archive, and access to metadata.

# Tar

```@docs
Copy link
Member

@stevengj stevengj Feb 6, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Expand Down
4 changes: 4 additions & 0 deletions src/Tar.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
"""
The `Tar` module provides a simple interface for handling tar archives, including creation of
archives, extraction of selected files from an archive, and access to metadata.
"""
module Tar

import SHA
Expand Down
6 changes: 6 additions & 0 deletions test/runtests.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1130,3 +1130,9 @@ end
end
end
end

if isdefined(Docs, :undocumented_names) # new in Julia 1.11
@testset "Docstrings" begin
@test isempty(Docs.undocumented_names(Tar))
end
end
Loading