dduan / drstring Goto Github PK
View Code? Open in Web Editor NEWDrString finds issues in your Swift docstrings and fixes them for you.
License: MIT License
DrString finds issues in your Swift docstrings and fixes them for you.
License: MIT License
Empty line required to separate docstring sections gets reported even tho there's no upcoming sections.
right now this is a valid entry for returns:
/// - returns: description blah blah
/// description continues.
… which is fine.
But one can see a use case where folks prefer (and therefore want to lint and format) the second line to start on the same column with the first line:
/// - returns: description blah blah
/// description continues.
When an docstring entry spans multiple lines, there's no option to join them in addition to breaking over-the-column-limit lines up to newlines. Sometimes user may prefer automatic joining behavior. For example, when authoring comments, I may add some words in one line of comment as an edit and it would be nice when this comment gets folded into multiple lines, the next line can join up with end of the last newly created lines, as opposed to stay on the next line.
check: lint, c, l
explain: e
similar to rg -l
. Turns out it's super useful to have a list of paths, ideally sorted and uniqued. It can be accomplished with piping into grep
/sort
/uniq
but the use case is common enough to justify a feature.
FileCheck based integration tests seems appropriate.
sometimes it's desirable to enforce it.
(question mark, exclamation point, etc)
/// blah blah blah
// <- notice how there are 2 `/`s
This should be a problem and be autoformattable.
When both grouped and separated doc style for parameters are present, it should be reported. This same option could be used for formatting
These should be two separate rules. When error occurs they should be detected and reported separately. If user does not specify preference for the first letter, the misspelled keywords should still be detected and reported.
The doc should answer these questions:
SAD!
whenever the literal whitespace is part of a problem description, and the problematic amount is 0 whitespace, it won't show up as a colored ANSI string (because there's no literal to color). The format need to be improved.
The correct behavior should be: ignore-throws makes missing throws a non-issue. But if a doc for throws does exist already, whitespace errors should be caught anyways.
there should be exactly 1 space. But currently it's unreported.
when new problems are added, and an explainer for it is missing, there's no automated way to catch this.
Enough said
The option should apply to all commands (main + sub). Today it only works for check
.
There should be an error / warning that reports superficial exclusions.
This could be useful when DrString is ran as an Xcode build step, for example.
Right now you'll get a problem for a missing doc, and a problem for a redundant doc. There might be a good algorithm out there that could infer this better.
The ads claim that this is a “formatter”. But as far as I can tell it only lints for issues. What gives?
Empty comment lines between sections are not getting added when missing (and required by user).
This is totally supported since the start. Should include it in GettingStarted and maybe even include a screenshot in README.
Modules/RequestFlow/Sources/Protocols/ModeSelectorBannerDisplayable.swift:0:0: warning: 1 docstring problem regarding ``
|E015| This file is explicitly excluded, but it has no docstring problems.
Because documentable name is empty string, you end up with a empty backtick quoted string at end of first line.
problem IDs are actually perfect matches for config options. Each option should have a linked problem ID section.
Use Github actions?
there should be an option for check
that takes a path to the config file.
This is a common-ish element. Should consider whether to check whitespace errors when it exists.
/// docstring starts 1 space off
func foo()
this should be problematic.
As long as a functions docstring item spelling and casing are consistent, it's good.
When user makes a mistake and forget to include a :
in - Parameters:
, currently this line will be rejected as a parameter header. This should be considered as a valid parameter group header, and reported as a problem.
Practical instructions to get folks started
check
and explain
Sometimes it's nice to describe the returned value as part of the description and the docs for - returns:
ends up being redundant.
/// Notice how `foo` doesn't have any content
///
/// - Parameter foo:
will be formatted into
/// Notice how `foo` doesn't have any content
///
/// - Parameter foo: ///
This could be part of overview or tutorial
A architecture.md would help a lot. In it the goofy module names should be explained (maybe even illustrated with comic characters?!?!?! too much?)
Ideally, when both provides options, they should be merged. Where there was an conflict, CLI should override config.
Logo should be Dr. Strange inspired. Font, if any, should resemble the title graphic of Dr. Strange in the Multiverse of Madness 😋
whenever code sample has empty lines, it gets interpreted as separators and the content below it becomes the next section.
CI should include running of this too of course
This was implemented as a linting rule but it's not exposed to users via an CLI/config option.
This should be part of development documentation
The stuff the cli app prints out is generally correct but really not good enough to get user anywhere. It should aim for self sufficiency and reference online documentation.
example:
For /// - paramater value: the value you want to ignore."
, DrString would refuse to recogonize this as a parameter, and report the parameter as missing.
The idea is sound but the implementation is naive. Right now, the help text is too wide due to potential enum values. And as far as I can tell there's no way to customize the text.
Maybe it's time to get rid of Guaka 😢.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.