<qyliss>
The Rust documentation is actually really nice for exploring a big multi-crate codebase like crosvm
<Shell>
Honestly rustdoc is one of the things Rust got really, really right.
<qyliss>
Yeah
<tazjin>
Shell: I have some minor nitpicks :3
<tazjin>
it'd be nice to be able to group items semantically, rather than by category
<tazjin>
(maybe that's a thing now)
<Shell>
tazjin: yeah, I agree, but good crate/module level documentation can paper over that - see e.g. smoltcp’s rustdoc
<tazjin>
agree
<qyliss>
Rust's documentation culture is really nice as well
<qyliss>
Like, Chromium OS is barely documented
<qyliss>
but there's some really nice stuff inside those crosvm docs, because it's just what you do when you're writing Rust
<qyliss>
and only because we have such great tools to extract that and present it so well, is it actually useful for getting an overview and searching and stuff
<tazjin>
qyliss: can you give me an example for a chromium OS thing that's badly documented?
<tazjin>
I'm wondering if they have internal docs that aren't public
<qyliss>
Let me have a click around
<qyliss>
or, actually, one from memory
<qyliss>
What is virtio_wl? How does it work? There are not really docs that answer that question.
<qyliss>
Another Googler told me there was not internal documentation, I believe.
<qyliss>
This lack of overview documentation is a big part of why I started writing this book
<tazjin>
it seems like they're right
<tazjin>
there's a few design docs that aren't public, but they're not really good as reference docs afaict
<qyliss>
It's okay
<qyliss>
I know how it works now
<tazjin>
yeah just curious in general why they don't document things
<qyliss>
And I shall write it down for other people :)
<tazjin>
maybe it's because they don't use g3doc with markdown, since they're on git :trollface:
<qyliss>
I guess this sort of thing is generally documented at Google?
<tazjin>
yes
<tazjin>
I find this sort of confirms what I said earlier about documentation structure
<qyliss>
tazjin: I'd love to have in-directory documentation like you described
<tazjin>
if this was an internal project I'd know where to look, but since it isn't it's like "lets use the internal search engine and see what happens"
<qyliss>
not sure how that would work when my main repository is nixpkgs, though
<qyliss>
I think having all of Spectrum in one huge repo with e.g. Nixpkgs subtrees would make it difficult to contribute
<tazjin>
I'd think that having spectrum as a set of commits on top of a nixpkgs tree is more difficult
<qyliss>
Well, it's not that either
<qyliss>
I see it as the Nixpkgs repo being extended with some other stuff, that builds a system
<qyliss>
Same way nixos is integrated into nixpkgs
<qyliss>
But, like, components I might want to document, like, say, crosvm, make this difficult
<qyliss>
Because I might have my own crosvm repo, as well as the crosvm package in Nixpkgs
<qyliss>
Where do the docs go?
<tazjin>
hmm, do you override the nixpkgs crosvm with your sources?
<tazjin>
I suspect that as long as this question is unanswered for nixpkgs you can't come up with a truly satisfying answer if you live in the nixpkgs tree
<qyliss>
Well, right now I'm using upstream Nixpkgs' crosvm unmodified
<qyliss>
And the way I do it for Sommelier, which I do modify, is I just put patches into the package directory rather than having a seperate sommelier tree
<qyliss>
Which is fine for the relatively small changes I make there
<qyliss>
But I think I might want to make quite big changes to crosvm to get it to do inter-guest virtio.
<qyliss>
To the point where keeping it all as patches in infeasible, and the desirable features of patches -- that it's easy to update the package as long as the patches stil apply, isn't relevant any more since there will probably be too many changes for that.
<qyliss>
I'm probably not communicating very well right now...
<tazjin>
you are, it makes perfect sense, I'm just thinking
<tazjin>
23:09:47 <qyliss> Same way nixos is integrated into nixpkgs <- nixos doesn't feel that integrated to me
<tazjin>
it's just like, a subfolder, mostly
<tazjin>
and then some strange intertwined deps with e.g. the options stuff from lib
<tazjin>
it'd feel more natural to me to have nixpkgs as a subfolder of the rest of the spectrum tree, that is consumed like a third_party thing
<qyliss>
That's what I meant, I guess
<qyliss>
It's integrated in the sense that you can atomically change NixOS and Nixpkgs together
<tazjin>
in which case the first-party things that you're writing all live at the top-level and have clearly defined docs locations
<qyliss>
I might well move to that.
<tazjin>
right
<qyliss>
Would be overkill right now, though.
<tazjin>
if you just subtree nixpkgs, then you get that (I think that's what edef does?)
<tazjin>
yeah, for now, but it'll probably become more difficult to detangle down the line
<qyliss>
Maybe.
<qyliss>
I think it's okay to wait and see a bit longer, though.
<qyliss>
Next milestone I want to hit involves actually figuring out how Nix configuration for Spectrum will work
<qyliss>
At that point, there'll start being a lot of Spectrum-specific code
<qyliss>
And then I probably will move to a subtree model.
<tazjin>
sounds reasonable
<qyliss>
But first I want to try to get inter-guest virtio into crosvm, because I realised when trying to tell potential contributors at Congress what they could work on that really we need it (or something like it but worse) before we can do any more communication between VMs, which is quite important.
<qyliss>
I don't have a milestone for that, though, so hopefully it's not too bad. >.<
<qyliss>
I don't think it will be
<qyliss>
mostly I just need to learn my way around the crosvm source, which will be useful anyway.