jlevy

Standard Documentation Guidelines

Version: v0.3 (last update 2026-05-05)
Joshua Levy (github.com/jlevy)

Purpose

Both agents and humans benefit from accurate, maintained documentation. These are brief and general guidelines for humans and agents when writing and organizing code, text files, and documentation.

jlevy

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Fetch rejected PRs and maintainer comments from a GitHub repo.

Uses `gh` CLI for authentication (must be logged in via `gh auth login`).

jlevy

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Fetch rejected PRs and maintainer comments from a GitHub repo.

Uses `gh` CLI for authentication (must be logged in via `gh auth login`).

jlevy

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = "==3.13"
# dependencies = [
#   "requests>=2.32.3",
#   "rich>=14.0.0",
#   "markdownify>=1.1.0",
#   "readabilipy>=0.3.0",
# ]
# ///

jlevy

"""
xontrib for fnm (Fast Node Manager) integration with xonsh shell.

Fnm is a good replacement for nvm and is compatible with .nvmrc.

Currently fnm doesn't support xonsh directly. This parses the bash output
of fnm and uses it within xonsh.
"""

import subprocess

jlevy

from typing import Set
from typing import NamedTuple


class Key(NamedTuple):
    name: str
    group: str


class Uniquifier:

jlevy

import {
  MARKDOWN_FORMAT_CHARS,
  truncate,
  truncateCondensed,
  truncateOnParagraphs,
  truncateOnWords,
} from './friendlyTruncate';

describe('truncate', () => {
  it('returns the input if it is null or shorter than the limit', () => {

jlevy

/**
 * Convenience for timing specific function calls and logging to console.
 * Works with both synchronous and asynchronous functions and also logs
 * if the function exited or had an exception. minMs is the minimum number
 * of milliseconds that the function must take to be logged.
 *
 * Usage example: To log when an expression like
 *
 * const result = someFunction(arg1, arg2);
 *

jlevy

import { comparisonChain, ordering } from './comparisonChain';

interface Item {
  title: string | null;
  url: string | null;
  sequenceNum: number | null;
}

// Setup a sample data
const items: Item[] = [

jlevy

// These hashes are for algorithmic use cases, such as bucketing in hashtables, where security isn't
// needed and 32 or 64 bits is enough (that is, rare collisions are acceptable). These are way simpler
// than sha1 (and all its deps) or similar, and with a short, clean (base 36 alphanumeric) result.

// A simple, *insecure* 32-bit hash that's short, fast, and has no dependencies.
// Output is always 7 characters.
// Loosely based on the Java version; see
// https://stackoverflow.com/questions/6122571/simple-non-secure-hash-function-for-javascript
const simpleHash = str => {
  let hash = 0;