|
| 1 | +# Plan: Add Backticks to All Julia Template Documentation |
| 2 | + |
| 3 | +## Summary |
| 4 | +Add backticks to all identifiers (parameter names, type names, function names, property names) in Julia template documentation to prevent markdown from misinterpreting underscores as italic formatting. |
| 5 | + |
| 6 | +## Files Already Fixed ✅ |
| 7 | +1. **julia-client/api.mustache** - Docstrings in generated Julia code (DONE) |
| 8 | +2. **julia-client/partial_model_doc_oneof.mustache** - Already has backticks |
| 9 | +3. **julia-client/partial_model_doc_anyof.mustache** - Already has backticks |
| 10 | +4. **julia-server/partial_model_doc_oneof.mustache** - Already has backticks |
| 11 | +5. **julia-server/partial_model_doc_anyof.mustache** - Already has backticks |
| 12 | + |
| 13 | +## Files Needing Changes |
| 14 | + |
| 15 | +### Priority 1: Markdown API Documentation |
| 16 | + |
| 17 | +#### 1. julia-client/api_doc.mustache |
| 18 | +**Issue**: Function signatures and parameter tables don't use backticks |
| 19 | + |
| 20 | +**Changes needed**: |
| 21 | +- Line 14: Function signature - wrap `operationId`, `paramName`, `dataType`, `returnType` in backticks |
| 22 | +- Line 15: Streaming signature - same as above |
| 23 | +- Line 25: Parameter name `{{paramName}}` → `` `{{paramName}}` `` |
| 24 | +- Line 26: Data types - add backticks around type names |
| 25 | +- Line 32: Optional parameter name - add backticks |
| 26 | +- Line 35-36: Return type - add backticks |
| 27 | + |
| 28 | +#### 2. julia-server/api_doc.mustache |
| 29 | +**Issue**: Same as client version |
| 30 | + |
| 31 | +**Changes needed**: |
| 32 | +- Line 14: Function signature - wrap `operationId`, `paramName`, `dataType`, `returnType` in backticks |
| 33 | +- Line 25: Parameter name - add backticks |
| 34 | +- Line 25: Data types - add backticks |
| 35 | +- Line 31: Optional parameter name - add backticks |
| 36 | +- Line 35: Return type - add backticks |
| 37 | + |
| 38 | +### Priority 2: Markdown Model Documentation |
| 39 | + |
| 40 | +#### 3. julia-client/model_doc.mustache |
| 41 | +**Issue**: Property names and types in tables don't use backticks |
| 42 | + |
| 43 | +**Changes needed**: |
| 44 | +- Line 13: `**{{name}}**` → `` **`{{name}}`** `` (property names) |
| 45 | +- Line 13: Type names - wrap `{{dataType}}` in backticks |
| 46 | + |
| 47 | +#### 4. julia-server/model_doc.mustache |
| 48 | +**Issue**: Same as client version |
| 49 | + |
| 50 | +**Changes needed**: |
| 51 | +- Same as julia-client/model_doc.mustache |
| 52 | + |
| 53 | +### Priority 3: README Documentation (Optional) |
| 54 | + |
| 55 | +#### 5. julia-client/README.mustache |
| 56 | +**Issue**: Identifiers in tables could use backticks for consistency |
| 57 | + |
| 58 | +**Changes needed** (optional): |
| 59 | +- Line 32: `` *{{classname}}* `` → `` *`{{classname}}`* `` |
| 60 | +- Line 32: `` **{{operationId}}** `` → `` **`{{operationId}}`** `` |
| 61 | +- Line 37: `` {{{classname}}} `` → `` `{{{classname}}}` `` |
| 62 | + |
| 63 | +#### 6. julia-server/README.mustache |
| 64 | +**Issue**: Same as client version (if exists) |
| 65 | + |
| 66 | +## Implementation Strategy |
| 67 | + |
| 68 | +### Phase 1: API Documentation (High Impact) |
| 69 | +1. Fix julia-client/api_doc.mustache |
| 70 | +2. Fix julia-server/api_doc.mustache |
| 71 | +3. Test with sample regeneration |
| 72 | + |
| 73 | +### Phase 2: Model Documentation (High Impact) |
| 74 | +1. Fix julia-client/model_doc.mustache |
| 75 | +2. Fix julia-server/model_doc.mustache |
| 76 | +3. Test with sample regeneration |
| 77 | + |
| 78 | +### Phase 3: README (Low Impact) |
| 79 | +1. Fix README.mustache files (optional enhancement) |
| 80 | +2. Final test with sample regeneration |
| 81 | + |
| 82 | +## Testing Checklist |
| 83 | + |
| 84 | +After each change: |
| 85 | +- [ ] Build openapi-generator |
| 86 | +- [ ] Regenerate Julia client samples: `./bin/generate-samples.sh ./bin/configs/julia-client*` |
| 87 | +- [ ] Regenerate Julia server samples: `./bin/generate-samples.sh ./bin/configs/julia-server*` |
| 88 | +- [ ] Verify backticks appear correctly in generated markdown files |
| 89 | +- [ ] Commit changes with descriptive message |
| 90 | + |
| 91 | +## Expected Outcome |
| 92 | + |
| 93 | +All generated markdown documentation will have identifiers wrapped in backticks: |
| 94 | +- `` `pet_id`::`Int64` `` instead of `pet_id::Int64` |
| 95 | +- `` `Custom_Type` `` instead of `Custom_Type` |
| 96 | +- `` `update_pet_with_form` `` instead of `update_pet_with_form` |
| 97 | + |
| 98 | +This prevents markdown processors from treating underscores as italic markers. |
0 commit comments