wolfSSH manual: rewrite and extend the API reference - #277
Open
ejohnstown wants to merge 2 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.
Comment on lines
+7
to
+10
| void wolfSSH_SetUserAuth(WOLFSSH_CTX* ctx , WS_CallbackUserAuth | ||
| cb ); | ||
| ``` | ||
| コールバック関数は、wolfSSH セッションオブジェクトを作成するために使用される wolfSSL CTX オブジェクトに設定されます。この CTX を使用するすべてのセッションは同じコールバック関数を使用します。このコンテキストは、コールバック関数のコンテキストと混同しないでください。 |
|
|
||
| リード・ライトをハンドリングするためのバッファサイズはデフォルトで1024バイトです。この値はアプリケーションがより少ないリソース消費に抑えたい場合やより大きなバッファが必要な場合には変更することができます。サイズ変更は`WOLFSSH_MAX_SFTP_RW`マクロを定義して行います。設定例は: | ||
| リード・ライトをハンドリングするためのバッファサイズはデフォルトで1024バイトです。この値はアプリケーションがより少ないリソース消費に抑えたい場合やより大きなバッファが必要な場合には変更することができます。デフォルトサイズの変更は、コンパイル時に`WOLFSSH_MAX_SFTP_RW`マクロを定義して行います。設定例は次のとおりです: | ||
|
|
Comment on lines
+140
to
+142
| wolfSSL のカスタムインストールディレクトリを設定するには、次のようにします: | ||
| ``` | ||
| $ ./configure --prefix=`~`/wolfSSL | ||
| $ ./configure --prefix=~/wolfSSL |
Comment on lines
+146
to
+148
| これにより、ライブラリは ~/wolfSSL/lib に、インクルードは ~/wolfssl/include に配置されます。wolfSSH のカスタムインストールディレクトリを設定し、カスタムの wolfSSL ライブラリおよびインクルードディレクトリを指定するには、次のようにします: | ||
| ``` | ||
| $ ./configure --prefix=`~`/wolfssh --libdir=`~`/wolfssl/lib --includedir=`~`/wolfssl/include | ||
| $ ./configure --prefix=~/wolfssh --libdir=~/wolfssl/lib --includedir=~/wolfssl/include |
|
|
||
| レポジトリをクローンした後、テスト用の秘密鍵はユーザーにとってはリードオンリーになっていることを確認してください。そうなっていない場合はssh_clientサンプルプログラムは警告します。 | ||
|
|
||
| レポジトリをクローンした後、テスト用の秘密鍵はユーザーにとってリードオンリーになっていることを確認してください。そうなっていない場合はssh_clientがそうするように警告します。 |
|
|
||
| ``` | ||
| $ ssh_client -p 22222 USER@localhost | ||
| $ ssh -p 22222 USER@localhost |
|
|
||
| ``` | ||
| $ ssh_client -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost | ||
| $ ssh -i ./keys/USER-key-TYPE.pem -p 22222 USER@localhost |
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