wolfSSH manual: rewrite and extend the API reference - #277
Open
ejohnstown wants to merge 8 commits into
Open
Conversation
Bring the wolfSSH API reference up to the current library API and standardize its format. - Reformat every entry in ch13 (core, ssh.h) and ch14 (SFTP, wolfsftp.h) to one consistent template: prototype block on top, then Description, Parameters, Return Values, See Also. Drop the empty Synopsis fields and the fragmented SFTP examples. - Document the full public API. ch13 now covers all 161 ssh.h functions (was 82) and ch14 all 28 public wolfsftp.h functions; test-internal SFTP helpers are intentionally excluded. - Add chapter 15 (SCP, wolfscp.h), chapter 16 (agent, keygen, log, certman, port), and chapter 17 (preprocessor guard macros). - Regenerate the ch13 error-code and I/O-error tables from error.h (the old values were stale) and add availability notes for guarded functions. - Fix numerous defects: wrong prototypes (e.g. SFTP offset args), inverted LSTAT symlink semantics, mislabeled Port Forwarding section, phantom keyboard-auth functions, and "wolfSSL SFTP" title typos. - Wire the new chapters into the Makefile and mkdocs nav (en/ja) and add Japanese placeholder chapters so the localized build still succeeds.
- Translate chapters 15-17 into Japanese. - Align chapters 01-14 with the current English text.
Contributor
There was a problem hiding this comment.
Pull request overview
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Updates the wolfSSH manual to match the current public API and standardize the API reference format across English and Japanese manuals.
Changes:
- Reformats and expands the SFTP API reference and adds new API reference chapters for SCP, agent/keygen/log/certman/portability, and preprocessor guard macros.
- Syncs and translates the new/updated documentation into the Japanese manual and refreshes several existing Japanese chapters.
- Updates MkDocs navigation and the documentation Makefile to include the new chapters.
Reviewed changes
Copilot reviewed 19 out of 21 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| wolfSSH/src/chapter14.md | Reformats/updates SFTP API reference entries to a consistent template. |
| wolfSSH/src/chapter15.md | Adds new SCP API reference chapter. |
| wolfSSH/src/chapter16.md | Adds new reference chapter for agent/keygen/logging/certman/portability APIs. |
| wolfSSH/src/chapter17.md | Adds a reference chapter for build-time feature/guard/tuning macros. |
| wolfSSH/src-ja/chapter14.md | Japanese SFTP API reference updated to match new English structure/content. |
| wolfSSH/src-ja/chapter15.md | Japanese translation of new SCP API reference. |
| wolfSSH/src-ja/chapter16.md | Japanese translation of new “Additional API Reference” chapter. |
| wolfSSH/src-ja/chapter17.md | Japanese translation of new preprocessor guard macros chapter. |
| wolfSSH/src-ja/chapter11.md | Updates support/consulting section formatting and contact info presentation. |
| wolfSSH/src-ja/chapter09.md | Clarifies SFTP attribute handling limitations text. |
| wolfSSH/src-ja/chapter07.md | Updates SFTP build/use instructions and examples. |
| wolfSSH/src-ja/chapter06.md | Updates user-auth callback documentation and adds keyboard-interactive prompt callback section. |
| wolfSSH/src-ja/chapter05.md | Expands user-auth data type docs (incl. keyboard-interactive) and refines wording/formatting. |
| wolfSSH/src-ja/chapter03.md | Refreshes “Getting Started” guidance and expands SCP/SFTP/shell/PQ/certs sections. |
| wolfSSH/src-ja/chapter02.md | Refreshes build instructions, autotools/Windows notes, and cross-compile guidance. |
| wolfSSH/src-ja/chapter01.md | Updates introduction/features list to current capabilities and certifications. |
| wolfSSH/mkdocs.yml | Adds new chapters (15–17) to English site navigation and renames SFTP entry. |
| wolfSSH/mkdocs-ja.yml | Adds new chapters (15–17) to Japanese site navigation and renames SFTP entry. |
| wolfSSH/Makefile | Includes new chapter markdown files in the docs build sources list. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Address PR review findings in the English manual text:
- chapter02: use ~/wolfSSL consistently for the custom install
example; the prose and the --libdir/--includedir example used
~/wolfssl while --prefix set ~/wolfSSL, which breaks copy/paste
builds on case-sensitive filesystems.
- chapter03: the key permission warning comes from the system ssh
client, and the commands shown use ssh; wolfSSH ships no
ssh_client program.
- chapter06: wolfSSH_SetUserAuth() takes a WOLFSSH_CTX, so the
callback is set on the wolfSSH CTX, not the wolfSSL one.
- chapter07: repair the C_EXTRA_FLAGS example. It was split across
two lines, used a smart quote with no closing quote, and omitted
the -D on the macro.
Mirror the English manual fixes into the Japanese translation:
- chapter02: use ~/wolfSSL consistently for the custom install
example.
- chapter03: name the system ssh client rather than a non-existent
ssh_client program.
- chapter06: the user authentication callback is set on the
WOLFSSH_CTX, not a wolfSSL CTX.
- chapter07: repair the C_EXTRA_FLAGS example.
Replace the curly quotes and apostrophes in chapters 2, 6, and 7 with their ASCII equivalents. Also drop the stray space in "read- only" in chapter 3.
Replace the curly quotes in chapters 2 and 7 with their ASCII equivalents, matching the English manual.
The example used --libdir and --includedir to point at wolfSSL. Those set wolfSSH's own install paths, not where wolfSSL is found. - Use --with-wolfssl instead - Note what --libdir and --includedir actually do - Update the English and Japanese manuals
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Brings the wolfSSH API reference up to the current library API (v1.5.0), standardizes its format, and resyncs the Japanese manual.
English manual, API reference
ssh.h) and ch14 (SFTP,wolfsftp.h) to one template: prototype block, Description, Parameters, Return Values, See Also. Dropped the empty Synopsis fields and the fragmented SFTP examples.ssh.hfunctions (was 82) and ch14 all 28 publicwolfsftp.hfunctions. Test-internal SFTP helpers are intentionally excluded.wolfscp.h), 16 (agent, keygen, log, certman, port), 17 (preprocessor guard macros).error.h(old values were stale) and add availability notes for guarded functions.Japanese manual