add missing docstrings for Base.Sys

[11happy]

Part of #52725 .
Thank you.

CC:

• @stevengj

[11happy]

Hello @stevengj & @inkydragon I have incorporated the suggested changes can you please look into it.
Thanks

[stevengj]

It seems like a historical artifact that we have both cpu_info() to get a Vector{CPUinfo} and cpu_summary() which gets a nice way to print it. I think this is because the function pre-dates the 3-argument show functions for pretty-printing at the REPL. We should really clean this up before we add anything to the manual.

It seems like we should just add a show method that displays a Vector{CPUinfo} via the easier-to-read cpu_summary() function, so users would never need to call cpu_summary() directly to get a nicer tabulated format:

function show(io::IO, ::MIME"text/plain", cpu::AbstractVector{CPUinfo})
    summary(io, cpu)
    println(io, ':')
    cpu_summary(io, cpu)
end

We can continue to export cpu_summary for backwards compatibility, but we shouldn't put it in the manual since there will be no reason to call it directly anymore.

Also, the show(io::IO, info::CPUinfo) method should really be a show(io::IO, ::MIME"text/plain", info::CPUinfo) method for pretty-printing — we should use the default 2-argument show (used in compact display like print) so that round-tripping with repr works, and the pretty-printed display should be a 3-argument show call (used e.g. by the REPL display function). Again, the current behavior is because this function pre-dated the 3-argument show.

And if we are documenting the CPUinfo struct, it should really be declared public and get its own docstring.

[stevengj]

Unrelated CI failures, should be good to merge.

[nsajko]

Ten different "update sysinfo.jl" commits being in git log is spammy.

[11happy]

Ten different "update sysinfo.jl" commits being in git log is spammy.

Those are actually the commit suggestions directly using Github UI as suggested by @stevengj .

[11happy]

I am sorry for such messy commit history,I will keep this in mind next time.

[nsajko]

It's not necessarily your fault (and it's not some huge issue anyway). I suppose @inkydragon should have squashed the commits while/before merging into master.

[stevengj]

I wish there was a way to disable anything but "squash and merge" on github for the whole repository. It's too easy to click "merge" instead by accident.

[stevengj]

It looks like it was squashed into a single commit eb26d63, so what's the problem?

[nsajko]

All the commits are now on the master branch, I see them cluttering my git log. Well, now I'm cluttering this PR's comments, but I always appreciated a tidy git history, as the commits on master are supposed to be somewhat permanent. For example, I see all of these in my git log for master:

d4e3a3d

adbf6b0

718740e

6cf7d26

06f5a4c

5e2cdbd

3309d86

Not a big deal in any case.

[stevengj]

Oh, I see, I was just looking at the merge commit. Looks like the same thing (merge, not squash-and-merge) happened with #52936 😢

[inkydragon]

Apologies for the mess, I didn't realize that the default merge method should be squash-and-merge.

Not sure if there is anything I can do to eliminate the mess.
From what I know of git, clearing existing commits requires git push --force, which is a dangerous
operation, and I'm not prepared to do it.

On the other hand, the default merge method is a convention that should probably be documented in devdoc.
I'm going to open a new pr later to document this convention.

And furthermore, Julia needs something like a Python developer's guide.
https://devguide.python.org/core-developers/committing/

[nsajko]

clearing existing commits requires git push --force, which is a dangerous operation, and I'm not prepared to do it.

Definitely don't do that, rewriting the history for master would cause real breakage. Although I know the Golang people actually did that at least once, I think because someone accidentally committed a big binary file or something.

On the other hand, the default merge method is a convention that should probably be documented in devdoc.
I'm going to open a new pr later to document this convention.

From what I've observed squash-and-merge is what people do here unless there's a label:"don't squash" label on the PR. That said, TBH it should be common sense not to put 30 redundant commits into the Git history.

[stevengj]

Besides simply reducing clutter, squashing is important because otherwise you will often get commits in the history that leave the repo in a broken state, breaking git bisect.

I agree that it should only be done retro-actively in drastic situations, and that it should be added to developer docs.

But I think that this is mainly a UI issue — it's just too easy to click the "merge" button accidentally, when in fact this should be marked as a dangerous action. Apparently there is a way to require squash-and-merge for a branch on github, so maybe we should do that: https://github.com/orgs/community/discussions/50593#discussioncomment-5402508 whoops, I should have read farther, apparently these instructions are a hallucination.

[stevengj]

I filed an issue about squash-merging (see link above) — let's continue further discussion there.