wroclaw-git-backups/nix
1
0
Fork 0
mirror of https://github.com/NixOS/nix synced 2025-07-01 08:28:00 +02:00
Code Activity

Finish converting existing comments for internal API docs (#8146)

Browse source 
* Finish converting existing comments for internal API docs

99% of this was just reformatting existing comments. Only two exceptions:

- Expanded upon `BuildResult::status` compat note

- Split up file-level `symbol-table.hh` doc comments to get
  per-definition docs

Also fixed a few whitespace goofs, turning leading tabs to spaces and
removing trailing spaces.

Picking up from #8133

* Fix two things from comments

* Use triple-backtick not indent for `dumpPath`

* Convert GNU-style `\`..'` quotes to markdown style in API docs

This will render correctly.
This commit is contained in:
John Ericson 2023-04-07 09:55:28 -04:00 • committed by GitHub
parent 54b3b6ebc6
commit 0746951be1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
53 changed files with 1907 additions and 938 deletions
Download patch file Download diff file Expand all files Collapse all files

52
src/libutil/archive.hh
View file

@ -20,39 +20,41 @@ namespace nix {
*
* The format is as follows:
*
* IF path points to a REGULAR FILE:
* dump(path) = attrs(
* [ ("type", "regular")
* , ("contents", contents(path))
* ])
* ```
* IF path points to a REGULAR FILE:
* dump(path) = attrs(
* [ ("type", "regular")
* , ("contents", contents(path))
* ])
*
* IF path points to a DIRECTORY:
* dump(path) = attrs(
* [ ("type", "directory")
* , ("entries", concat(map(f, sort(entries(path)))))
* ])
* where f(fn) = attrs(
* [ ("name", fn)
* , ("file", dump(path + "/" + fn))
* ])
* IF path points to a DIRECTORY:
* dump(path) = attrs(
* [ ("type", "directory")
* , ("entries", concat(map(f, sort(entries(path)))))
* ])
* where f(fn) = attrs(
* [ ("name", fn)
* , ("file", dump(path + "/" + fn))
* ])
*
* where:
* where:
*
* attrs(as) = concat(map(attr, as)) + encN(0)
* attrs((a, b)) = encS(a) + encS(b)
* attrs(as) = concat(map(attr, as)) + encN(0)
* attrs((a, b)) = encS(a) + encS(b)
*
* encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
* encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
*
* encN(n) = 64-bit little-endian encoding of n.
* encN(n) = 64-bit little-endian encoding of n.
*
* contents(path) = the contents of a regular file.
* contents(path) = the contents of a regular file.
*
* sort(strings) = lexicographic sort by 8-bit value (strcmp).
* sort(strings) = lexicographic sort by 8-bit value (strcmp).
*
* entries(path) = the entries of a directory, without `.' and
* `..'.
* entries(path) = the entries of a directory, without `.` and
* `..`.
*
* `+' denotes string concatenation.
* `+` denotes string concatenation.
* ```
*/
void dumpPath(const Path & path, Sink & sink,
PathFilter & filter = defaultPathFilter);
@ -88,7 +90,7 @@ struct ParseSink
/**
* If the NAR archive contains a single file at top-level, then save
* the contents of the file to `s'. Otherwise barf.
* the contents of the file to `s`. Otherwise barf.
*/
struct RetrieveRegularNARSink : ParseSink
{