dduan / drstring Goto Github PK

/// blah blah blah
// <- notice how there are 2 `/`s

This should be a problem and be autoformattable.

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 😢.

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 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.

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.

As long as a functions docstring item spelling and casing are consistent, it's good.

check: lint, c, l
explain: e

This should be part of development documentation

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.

Practical instructions to get folks started

• Usage of CLI for check and explain
• Usage with config

• Pre-dash space
• Space between dash and keyword
• Keyword spelling

there should be an option for check that takes a path to the config file.

Empty comment lines between sections are not getting added when missing (and required by user).

Sometimes it's nice to describe the returned value as part of the description and the docs for - returns: ends up being redundant.

Ideally, when both provides options, they should be merged. Where there was an conflict, CLI should override config.

This could be part of overview or tutorial

This was implemented as a linting rule but it's not exposed to users via an CLI/config option.

There should be an error / warning that reports superficial exclusions.

Enough said

there should be exactly 1 space. But currently it's unreported.

Logo should be Dr. Strange inspired. Font, if any, should resemble the title graphic of Dr. Strange in the Multiverse of Madness 😋

A architecture.md would help a lot. In it the goofy module names should be explained (maybe even illustrated with comic characters?!?!?! too much?)

CI should include running of this too of course

Use Github actions?

This is totally supported since the start. Should include it in GettingStarted and maybe even include a screenshot in README.

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.

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.

Empty line required to separate docstring sections gets reported even tho there's no upcoming sections.

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.

The doc should answer these questions:

• what is a docstring?
• what's DrString's relationship to docstrings?
• (maybe) glossary?

 /// docstring starts 1 space off
func foo()

this should be problematic.

FileCheck based integration tests seems appropriate.

problem IDs are actually perfect matches for config options. Each option should have a linked problem ID section.

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.

When both grouped and separated doc style for parameters are present, it should be reported. This same option could be used for formatting

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.

sometimes it's desirable to enforce it.

(question mark, exclamation point, etc)

/// 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 useful when DrString is ran as an Xcode build step, for example.

The option should apply to all commands (main + sub). Today it only works for check.

when new problems are added, and an explainer for it is missing, there's no automated way to catch this.

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.

SAD!

This is a common-ish element. Should consider whether to check whitespace errors when it exists.

The ads claim that this is a “formatter”. But as far as I can tell it only lints for issues. What gives?

whenever code sample has empty lines, it gets interpreted as separators and the content below it becomes the next section.

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.