Added new extension settings for including example section and only include pub/extern examples section.

Added a expanded safety section to include more detail for the safety section.
Updated Workflow file as well as the package.

Author: chrisdbeard

.github/workflows/test_and_publish.yml

@@ -47,6 +47,17 @@ jobs:
 
       - run: npm ci
 
+      - name: Move [Unreleased] to new version in CHANGELOG
+        run: |
+          VERSION="${GITHUB_REF##*/}"
+          DATE=$(date +%Y-*m-%d)
+          sed -i.bak "0,/## \[Unreleased\]/s//## [Unreleased]\n\n## [${VERSION}] - ${DATE}/" CHANGELOG.md
+          rm CHANGELOG.md.bak
+          git config user.name "github-actions"
+          git config user.email "github-actions@github.com"
+          git commit -am "chore: update CHANGELOG for ${VERSION}"
+          git push
+
       - name: Github Release
         uses: softprops/action-gh-release@v1
         with:

.gitignore

@@ -2,3 +2,4 @@ node_modules
 .vscode-test/
 *.vsix
 .env
+releases

CHANGELOG.md

@@ -3,8 +3,11 @@
 ## [Unreleased]
 
 - Extension settings
+  - Added setting `rustdocstring.includeExamples`
+  - Added setting `rustdocstring.examplesOnlyForPublicOrExtern`
+  - Added setting `rustdocstring.includeSafetyDetails`
 
-## [0.1.1] Initial release - 2025-05-03
+## [v0.1.1] Initial release - 2025-05-04
 
 - Initial release with support for `fn`, `struct`, and `enum` Rust items
 - Context-aware comment generation

README.md

@@ -54,6 +54,24 @@
 
 ---
 
+## Configuration Options
+
+The Rust Doc String extension supports several settings to control the generated documentation style. These can be set in your `settings.json` or through the VSCode Settings UI.
+
+| Setting | Description | Default |
+|--------|-------------|---------|
+| `rustdocstring.includeExamples` | Include the `# Examples` section in generated doc comments. | `true` |
+| `rustdocstring.examplesOnlyForPublicOrExtern` | Only include examples for functions marked `pub` or `extern`. Requires `includeExamples` to be enabled. | `false` |
+| `rustdocstring.inludeSafetyDetails` | Include detailed safety requirements in the `# Safety` section for `unsafe` or `extern` functions. | `false` |
+
+You can update these by searching for “Rust Doc String Generator” or "rustdocstring" in the VSCode Settings UI or by adding them to your `settings.json`:
+
+```json
+"rustdocstring.includeExamples": true,
+"rustdocstring.examplesOnlyForPublicOrExtern": false,
+"rustdocstring.inludeSafetyDetails": false
+```
+
 ## How It Works
 
 RustDocString uses a signature parser (`utils.js`) to scan for the next Rust item and normalize its declaration. Then, depending on the item type:

package.json

@@ -56,7 +56,28 @@
           "Rust"
         ]
       }
-    ]
+    ],
+    "configuration": {
+      "title": "Rust Doc String Generator",
+      "properties": {
+        "rustdocstring.includeExamples": {
+          "type": "boolean",
+          "default": true,
+          "description": "Include the '# Examples' section in generated Rust documentation."
+        },
+        "rustdocstring.examplesOnlyForPublicOrExtern": {
+          "type": "boolean",
+          "default": false,
+          "description": "Only include examples for functions marked 'pub' or 'extern'.",
+          "markdownDescription": "This applies only if `includeExamples` is enabled."
+        },
+        "rustdocstring.includeSafetyDetails": {
+          "type": "boolean",
+          "default": false,
+          "description": "Include extended detailed safety requirments in the '# Safety' section for unsafe or extern functions."
+        }
+      }
+    }
   },
   "scripts": {
     "lint": "eslint .",

src/docgen.js

@@ -1,6 +1,7 @@
 const { generateFunctionDoc } = require('./gen_fn_doc.js');
 const { generateStructDoc } = require('./gen_struct_doc.js');
 const { generateEnumDoc } = require('./gen_enum_doc.js');
+const vscode = require('vscode');
 
 /**
  * Dispatcher for generating Rust doc comments based on the type of code item.
@@ -10,20 +11,25 @@ const { generateEnumDoc } = require('./gen_enum_doc.js');
  * @returns {string|null} - The formatted doc comment, or null if unsupported.
  */
 function generateDocComment(line) {
+    const config = vscode.workspace.getConfiguration('rustdocstring');
+    const includeExamples = config.get('includeExamples', true);
+    const examplesOnlyForPublicOrExtern = config.get('examplesOnlyForPublicOrExtern', false);
+    const includeSafetyDetails = config.get('includeSafetyDetails', false);
+
     const itemType = getRustItemType(line);
     if (!itemType) return null;
 
     switch (itemType) {
         case 'function':
-            return generateFunctionDoc(line);
+            return generateFunctionDoc(line, includeExamples, examplesOnlyForPublicOrExtern, includeSafetyDetails);
         case 'struct':
-            return generateStructDoc(line);
+            return generateStructDoc(line, includeExamples, examplesOnlyForPublicOrExtern);
         case 'enum':
-            return generateEnumDoc(line);
+            return generateEnumDoc(line, includeExamples, examplesOnlyForPublicOrExtern);
         // case 'trait': // TODO
-        //     return generateTraitDoc(line);
+        //     return generateTraitDoc(line, includeExamples);
         // case 'union': // TODO
-        //     return generateUnionDoc(line);
+        //     return generateUnionDoc(line, includeExamples);
         default:
             return null;
     }

src/gen_enum_doc.js

@@ -11,7 +11,10 @@
  * @param {string} line - The line containing the Rust `enum` declaration with its body.
  * @returns {string|null} A formatted doc comment block or null if parsing fails.
  */
-function generateEnumDoc(line) {
+function generateEnumDoc(line, includeExamples, examplesOnlyForPublicOrExtern) {
+    // Check if enum is public or externed.
+    const isPublicOrExtern = /\b(pub(\s*\([^)]*\)|\s+self|\s+super)?|extern(\s*"[^"]*")?)\b/.test(line);
+
     // Remove trailing comments and trim whitespace
     line = line.replace(/\/\/.*$/, '').trim();
 
@@ -60,12 +63,14 @@ function generateEnumDoc(line) {
 
     const defaultVariant = variants[0].split(/[({]/)[0].trim();
 
-    // Examples section
-    docLines.push(``, `# Examples`, ``, '```', `use crate::\${${currentTabStop++}:...};`, ``);
-    docLines.push(`let ${name.toLowerCase()} = ${name}::${defaultVariant};`); // Add function name.
-    docLines.push(...exampleLines);
-    docLines.push('}');
-    docLines.push('```'); // End the example section markdown code block
+    if (includeExamples && (!examplesOnlyForPublicOrExtern || isPublicOrExtern)) {
+        // Examples section
+        docLines.push(``, `# Examples`, ``, '```', `use crate::\${${currentTabStop++}:...};`, ``);
+        docLines.push(`let ${name.toLowerCase()} = ${name}::${defaultVariant};`); // Add function name.
+        docLines.push(...exampleLines);
+        docLines.push('}');
+        docLines.push('```'); // End the example section markdown code block
+    }
 
     // Format as Rust doc comment block
     return [docLines[0], ...docLines.slice(1).map(line => `/// ${line}`)].join('\n');

src/gen_fn_doc.js

@@ -15,7 +15,10 @@
  * @param {string} line - The normalized function signature, stripped of leading comments or extra lines.
  * @returns {string|null} The formatted Rust doc comment block as a string, or `null` if the input is not a valid function signature.
  */
-function generateFunctionDoc(line) {
+function generateFunctionDoc(line, includeExamples, examplesOnlyForPublicOrExtern, includeSafetyDetails) {
+    // Check if function is public or externed.
+    const isPublicOrExtern = /\b(pub(\s*\([^)]*\)|\s+self|\s+super)?|extern(\s*"[^"]*")?)\b/.test(line);
+
     // Strip pub, pub(crate), pub(in ...), pub(self), pub(super)
     const cleanLine = line.replace(/pub(\s*\([^)]*\)|\s+self|\s+super)?\s+/, '');
 
@@ -73,10 +76,13 @@ function generateFunctionDoc(line) {
     if (hasUnsafe || hasExtern) {
         // Check if unsafe and extern
         docLines.push(``, `# Safety`, ``);
-        docLines.push(`- **The caller must ensure that:**`);
-        docLines.push(`  - Any internal state or memory accessed by this function is in a valid state.`);
-        docLines.push(`  - Preconditions specific to this function's logic are satisfied.`);
-        docLines.push(`  - This function is only called in the correct program state to avoid UB.`);
+
+        if (includeSafetyDetails) {
+            docLines.push(`- **The caller must ensure that:**`);
+            docLines.push(`  - Any internal state or memory accessed by this function is in a valid state.`);
+            docLines.push(`  - Preconditions specific to this function's logic are satisfied.`);
+            docLines.push(`  - This function is only called in the correct program state to avoid UB.`);
+        }
 
         if (hasUnsafe) {
             // Check if also unsafe
@@ -94,12 +100,12 @@ function generateFunctionDoc(line) {
         docLines.push(`\${${currentTabStop++}:Describe possible errors.}`);
     }
 
-    // TODO Make editable configuration to include example sections as a checkbox in the settings.
-
-    // Examples section
-    const { exampleLines, nextTabStop } = createExampleSection(name, currentTabStop, hasAsync, hasUnsafe);
-    docLines.push(...exampleLines); // add example section
-    currentTabStop = nextTabStop; // Update counter
+    if (includeExamples && (!examplesOnlyForPublicOrExtern || isPublicOrExtern)) {
+        // Examples section
+        const { exampleLines, nextTabStop } = createExampleSection(name, currentTabStop, hasAsync, hasUnsafe);
+        docLines.push(...exampleLines); // add example section
+        currentTabStop = nextTabStop; // Update counter
+    }
 
     // Prefix all lines with Rust doc syntax (`///`) and return as a snippet string
     return [

src/gen_struct_doc.js

@@ -18,7 +18,10 @@
  * @param {string} line - A string containing the full struct declaration, including its body.
  * @returns {string|null} The formatted doc comment block, or `null` if the input is not a valid documentable struct.
  */
-function generateStructDoc(line) {
+function generateStructDoc(line, includeExamples, examplesOnlyForPublicOrExtern) {
+    // Check if struct is public or externed.
+    const isPublicOrExtern = /\b(pub(\s*\([^)]*\)|\s+self|\s+super)?|extern(\s*"[^"]*")?)\b/.test(line);
+
     // Reject unit structs (single struct no fields)
     if (/struct\s+\w+\s*(;|\{\})/.test(line)) return null; // Struct ends with ';' or '{}'
 
@@ -60,25 +63,27 @@ function generateStructDoc(line) {
         docLines.push(``, `# Fields`, ``, ...fields);
     }
 
-    // Examples section
-    docLines.push(``, `# Examples`, ``, '```', `use crate::\${${currentTabStop++}:...};`, ``);
+    if (includeExamples && (!examplesOnlyForPublicOrExtern || isPublicOrExtern)) {
+        // Examples section
+        docLines.push(``, `# Examples`, ``, '```', `use crate::\${${currentTabStop++}:...};`, ``);
 
-    if (body.startsWith('{')) {
-        // Field-style struct
-        docLines.push(`let s = ${name} {`);
-        for (const field of fields) {
-            const fieldName = field.match(/`([^`]+)`/)[1]; // extract field name
-            docLines.push(`    ${fieldName}: value,`);
+        if (body.startsWith('{')) {
+            // Field-style struct
+            docLines.push(`let s = ${name} {`);
+            for (const field of fields) {
+                const fieldName = field.match(/`([^`]+)`/)[1]; // extract field name
+                docLines.push(`    ${fieldName}: value,`);
+            }
+            docLines.push(`};`);
+        } else if (body.startsWith('(')) {
+            // Tuple-style struct
+            const types = body.slice(1, -1).split(',').map(t => t.trim()).filter(Boolean);
+            const tupleArgs = types.map(() => `value`).join(', ');
+            docLines.push(`let s = ${name}(${tupleArgs});`);
         }
-        docLines.push(`};`);
-    } else if (body.startsWith('(')) {
-        // Tuple-style struct
-        const types = body.slice(1, -1).split(',').map(t => t.trim()).filter(Boolean);
-        const tupleArgs = types.map(() => `value`).join(', ');
-        docLines.push(`let s = ${name}(${tupleArgs});`);
-    }
 
-    docLines.push('```'); // End the example section markdown code block
+        docLines.push('```'); // End the example section markdown code block
+    }
 
     // Format as Rust doc comment block
     return [docLines[0], ...docLines.slice(1).map(line => `/// ${line}`)].join('\n');