doc: document return value of dgram.Socket methods

[BIGSUS24]

Both socket.bind() overloads and socket.close() return the socket itself, but the docs for all three don't mention a return value. socket.ref() and socket.unref() a few sections down already document Returns: {dgram.Socket}, so this is an inconsistency inside dgram.md rather than a new convention.

How I verified this

Against the source, on current main:

• Socket.prototype.bind() ends with return this;, and each of its early exits (replaceHandle path, cluster path, fd path) also returns this. The bare return; statements are inside the async state.handle.lookup() callback, not the outer function, so bind() returns the socket on every path.
• Socket.prototype.close() returns this on both its paths (queued and immediate).

At runtime on v22.14.0:

const dgram = require('dgram');
const s = dgram.createSocket('udp4');
console.log(s.bind(0) === s);            // true
s.on('listening', () => {
  console.log(s.close() === s);          // true
});

const s2 = dgram.createSocket('udp4');
console.log(s2.bind({ port: 0 }) === s2); // true

Not included

socket.setTTL(), socket.setMulticastTTL() and socket.setMulticastLoopback() also return a value (their own argument), but that looks like a legacy quirk — setMulticastLoopback is literally annotated // 0.4 compatibility in lib/dgram.js. I left those alone rather than pin down behaviour that may not be intended as API. Happy to add them if you'd prefer the file to be exhaustive.

---

Disclosure per AGENTS.md: I used a coding agent (Claude Code) to scan doc/api/*.md against lib/ for documented methods with undocumented return values. I read each hit in the source myself and ran the runtime checks above before opening this; the exclusions above are my own call.

[nodejs-github-bot]

Review requested:

• @nodejs/net

[Copilot]

Copilot review overview

🟢 Approval recommended

The documentation matches existing behavior and has no unresolved review comments.

Review effort: Lite
Findings: None

What changed in this PR

Documents existing return values for dgram.Socket methods.

Changes:

• Documents {dgram.Socket} returns for both bind() overloads.
• Documents the {dgram.Socket} return for close().

File	Summary
doc/​api/​dgram.md	Documents socket return values for bind() and close().

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.