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.

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 basic docs for (Lazy)Artifacts stdlibs #39073

Merged
merged 1 commit into from
Jan 26, 2021

Conversation

fingolfin
Copy link
Member

Some progress on #38462. Certainly could be improved but it's a start.

@simeonschaub simeonschaub added backport 1.6 Change should be backported to release-1.6 docs This change adds or pertains to documentation stdlib Julia's standard library labels Jan 2, 2021
@simeonschaub
Copy link
Member

Looks like the module needs to be explicitly specified in the doctests of split_artifact_slash here.

Artifacts.artifact_meta
Artifacts.artifact_hash
Artifacts.find_artifacts_toml
Artifacts.@artifact_str
Copy link
Member Author

Choose a reason for hiding this comment

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

BTW in case anybody wonders why these four functions and not others: I took the Artifacts API reference in the Pkg.jl documentation and extracted all functions from there which also are in Artifacts.jl, and put them in the above list. That seemed safest: these are functions somebody already decided should appear in a public manual. I think there are a few with docstrings which should not appear here (they are rather about implementation details), but perhaps a few more should appear? In any case, I rather don't want to be the person to decide that; but I'll happily add more here if people request it.

@fingolfin
Copy link
Member Author

Fixed the first doctest issue, but that now revealed an actual (?) issue in the doctest.

@fingolfin
Copy link
Member Author

The doctest problem is caused by the need to double quote backslashes in strings TWICE in regular doc comments: The source code has this in the doc comment:

julia> ret = split_artifact_slash("Foo\\bar\\baz.so");

but this is of course inside a triple-quoted string, so one level of quoting is removed, so the actual content of the doc string are:

julia> ret = split_artifact_slash("Foo\bar\baz.so");

and so the \b are treated as control characters.

One fix (that I just applied) is to use \\\\ but here I chose to instead switch the docstring to a raw string because this was more legible. But if people prefer a different solution, let me know.

@KristofferC KristofferC mentioned this pull request Jan 19, 2021
60 tasks
@vchuravy vchuravy closed this Jan 25, 2021
@vchuravy vchuravy reopened this Jan 25, 2021
@vchuravy vchuravy requested a review from staticfloat January 25, 2021 14:59
@staticfloat staticfloat merged commit debf26e into JuliaLang:master Jan 26, 2021
KristofferC pushed a commit that referenced this pull request Jan 26, 2021
@KristofferC KristofferC removed the backport 1.6 Change should be backported to release-1.6 label Feb 1, 2021
KristofferC pushed a commit that referenced this pull request Feb 1, 2021
ElOceanografo pushed a commit to ElOceanografo/julia that referenced this pull request May 4, 2021
antoine-levitt pushed a commit to antoine-levitt/julia that referenced this pull request May 9, 2021
@fingolfin fingolfin deleted the mh/artifact-docs branch July 7, 2021 10:01
staticfloat pushed a commit that referenced this pull request Dec 23, 2022
vchuravy pushed a commit to JuliaPackaging/LazyArtifacts.jl that referenced this pull request Oct 2, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation stdlib Julia's standard library
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants