Skip to content

Add API reference and guides under doc/ - #603

Open
laruence wants to merge 3 commits into
masterfrom
doc/api-manual
Open

Add API reference and guides under doc/#603
laruence wants to merge 3 commits into
masterfrom
doc/api-manual

Conversation

@laruence

Copy link
Copy Markdown
Owner

Summary

Yaf has been carrying an old Chinese manual (doc.laruence.com-era HTML) with known transcription errors (e.g. isOption vs isOptions, geModules) and no documentation for 3.3.x behavior changes. This adds a fresh manual under doc/ built on two guarantees:

  • Signatures are never hand-written. All class/method signatures are generated via Reflection from the loaded extension, so they match exactly what the C code registers.
  • Prose is cross-checked against 3.3.8-dev sources, including recent fixes: yaf.forward_limit=0 now clamps to the default (previously an infinite loop), Dispatcher::getInstance() requires an initialized Application, Session resolves $_SESSION from the symbol table on every access.

Contents

Section What's in it
classes/ 38 class/interface pages, 233 own methods — each with description, param notes, return semantics and runnable examples
guides/quick-start.md minimal working app from scratch
guides/lifecycle.md full request path with plugin-hook timeline (verified against YAF_PLUGIN_HANDLE call sites)
guides/directory-conventions.md class-name → file-path mapping rules (verified against yaf_loader.c)
guides/routing.md 6 built-in routes, selection matrix, custom routes, URL assembling
guides/error-handling.md throwException × catchException behavior matrix, error-code ↔ exception table
constants.md / ini.md all YAF_ERR_* constants and ini directives with defaults
llms.txt / llms-full.txt AI-friendly entry points (index + full-manual single file)

Descriptions are in Chinese; signatures and examples are language-neutral. Prose lives in doc/annotations/ separated from signatures, so the two can evolve independently.

Test plan

  • Read through doc/guides/lifecycle.md and doc/guides/directory-conventions.md (the two most source-sensitive pages)
  • Spot-check a few class pages against current sources
  • Verify markdown renders cleanly on GitHub

Signatures are generated via Reflection from the loaded extension, so
they always match what the code registers -- no hand-transcribed
typos like the ones in the old manual (isOption/geModules). Descriptions
and examples are cross-checked against the 3.3.8-dev sources, including
recent behavior changes (forward_limit=0 now clamps to the default,
Dispatcher::getInstance requires an initialized Application, Session
no longer keeps a stale $_SESSION pointer).

- classes/: 38 class/interface pages, 233 own methods documented
- guides/: quick-start, lifecycle (plugin hook timeline),
  directory-conventions (loader naming rules), routing, error-handling
- llms.txt / llms-full.txt: AI-friendly entry points
The llms.txt convention is a site/repo-root convention, so the AI entry
points are easier to discover at the top level. Internal links are
rewritten with the doc/ prefix accordingly; doc/README.md updated.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant