Page MenuHomeFreeBSD

[1/3] queue.3: Document existing QMD_* macros
ClosedPublic

Authored by cem on Oct 22 2015, 7:51 PM.
Tags
None
Referenced Files
Unknown Object (File)
Sun, Nov 17, 2:49 PM
Unknown Object (File)
Sun, Nov 17, 2:43 PM
Unknown Object (File)
Fri, Nov 15, 2:19 PM
Unknown Object (File)
Mon, Nov 4, 10:05 PM
Unknown Object (File)
Mon, Nov 4, 10:05 PM
Unknown Object (File)
Mon, Nov 4, 10:05 PM
Unknown Object (File)
Mon, Nov 4, 10:05 PM
Unknown Object (File)
Mon, Nov 4, 9:48 PM
Subscribers

Diff Detail

Event Timeline

cem retitled this revision from to [1/3] queue.3: Document existing QMD_* macros.
cem updated this object.
cem edited the test plan for this revision. (Show Details)
cem added a reviewer: emaste.
share/man/man3/queue.3
35–36 ↗(On Diff #9631)

Don't want to get caught in a bikeshed over this, but I'm not an mdoc expert; it seems odd to me.

1255 ↗(On Diff #9631)

Interesting -- when I added these I didn't anticipate that anyone would use them directly, but rather that consistency be checked via LIST_INSERT_HEAD etc.

share/man/man3/queue.3
35–36 ↗(On Diff #9631)

I'll try to sum up IRC consensus:

  1. It's slightly wrong; it should just be .Nm queue
  2. (queue(3) to distinguish the pagename from the generic word 'queue')
  3. But we also shouldn't have a million other .Nms — the em dash logically separates the page name from the macros therein
  4. (But maybe we should, because they're all MLINKed to queue.3 itself.)
  5. But also mdoc(7) is badly adapted to section 3 and 9, and maybe its provisions about argument-less .Nm use are wrong anyway.
  6. Strong vote of confidence from Baptiste "your approach is probably the less worse :)"
1255 ↗(On Diff #9631)

Yeah, and they probably shouldn't be. Maybe this part should be moved to queue.h instead.

bdrewery added inline comments.
share/man/man3/queue.3
1255 ↗(On Diff #9631)

Yeah, I think we should keep these private.

share/man/man3/queue.3
1255 ↗(On Diff #9631)

Can remove.

So, we don't want a man page update, and this should just be queue.h comments?

cem edited edge metadata.

Move macro documentation from man page to header.

This revision was automatically updated to reflect the committed changes.