swagger-api / swagger-api/swagger-codegen
Maven plugin skipOverwrite documentation is ambiguous
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
The skipOverwrite property is documented as follows: "Specifies if the existing files should be overwritten during the generation."
Apart from being grammatically incorrect (use of 'if' incorrect; should be 'whether'), it's unclear whether a value of true would or would not overwrite existing files. It's also unclear whether the check takes account of whether the generated files are up to date timestamp-wise with respect to the source YAML/JSON.
If the property does not take account of up-to-date-ness, then I can't see what use it is and I can't see why it isn't just called 'skip' like every other Maven plug-in. If the property does take account of up-to-date-ness, then I can't see why it is necessary in the first place.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the Maven plugin documentation for the skipOverwrite property, then read its implementation to establish what true does and whether timestamps affect the decision. Done means the documentation clearly describes the behavior and resolves the ambiguity raised in the issue.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100