detekt-generator code examples #584
Conversation
|
|
||
| import java.io.File | ||
|
|
||
| class CodeExampleCollector { |
There was a problem hiding this comment.
this should probably extend Collector so that it can run together with all the other collectors.
There was a problem hiding this comment.
Yeah, maybe. The CodeExampleCollector does not need the visit() method.
| @@ -23,11 +25,13 @@ class DetektCollector : Collector<RuleSetPage> { | |||
| val rules = ruleCollector.items | |||
| val multiRules = multiRuleCollector.items.associateBy({ it.name }, { it.rules }) | |||
| val ruleSets = ruleSetProviderCollector.items | |||
| val codeExamples = codeExampleCollector.collect() | |||
There was a problem hiding this comment.
This should be part of the collectors List and then it will run as part of the visit method. codeExampleCollector.items will give you the collected Set.
There was a problem hiding this comment.
The CodeExampleCollector does not need the visit() method.
| val rules: List<RuleCode> | ||
| ) | ||
|
|
||
| data class RuleCode( |
There was a problem hiding this comment.
Why don't we add the codeExample property to Rule?
There was a problem hiding this comment.
The CodeExample needs to be associated with the corresponding rule.
| @@ -42,6 +42,8 @@ inline fun MarkdownContent.referenceToHeading(reference: () -> String) = | |||
| "[${reference()}](#${reference().replace(' ', '-')})" | |||
|
|
|||
| inline fun MarkdownContent.code(code: () -> String) = "`${code()}`" | |||
| inline fun MarkdownContent.kotlinCode(code: () -> String) = "```kotlin\n${code()}\n```" | |||
There was a problem hiding this comment.
I guess Markdown would call this a code block?
| return emptySet() | ||
| } | ||
|
|
||
| private fun collectExamples(): Set<CodeExample> { |
There was a problem hiding this comment.
Where would the examples for compliant/non-compliant code live? Also in the KDoc of a rule? Then we could use a Visitor similar to the RuleCollector. Or should these be completely separate files? In that case it would be hard to link them and to remember to add/update them everytime rules get added/changed because they are so out of sight.
There was a problem hiding this comment.
No. As I mentioned in the initial comment:
Do you have an idea where to put the text files with the code examples?
I think detekt should have them in separate text files (possibly with the same name as the rule itself).
There was a problem hiding this comment.
I fear that this "hides" them a little bit and makes very obfuscated where the samples are coming from. Also for Contributors it would not be very obvious that these samples even exist.
There was a problem hiding this comment.
I agree. However, I don't like it in the comment of the rule implementation either.
There was a problem hiding this comment.
Didn't we say to put the code examples into the kdoc together with the description?
There was a problem hiding this comment.
I think the rule implementation gets bloated. The code examples don’t provide any additional value to the implementation except for the generated documentation.
There was a problem hiding this comment.
@arturbosch that’s the advantage of the inline solution
There was a problem hiding this comment.
Hiding code examples makes the codebase harder understand and fully comprehend imo. It will be really easy to forget adding/keeping those examples up-to-date when they are so out of sight. Having everything in one place in the KDoc of the rule class at least makes it a little more visible and more likely that contributors and the people reviewing PRs remember that the examples should be updated.
There was a problem hiding this comment.
This could be avoided by a simple test as I mentioned.
Anyways, the votes are against this solution. I can of course live with that. I’ll adapt this prototype soon.
There was a problem hiding this comment.
Thanks for the open discussion and the review!
| } | ||
| ``` | ||
|
|
||
| #### Compliant Code: |
There was a problem hiding this comment.
I think the Compliant and Noncompliant code snippets are mixed
This PR implements a prototype for compliant and non-compliant code-examples in the documentation generator as discussed in #343.
Do you have an idea where to put the text files with the code examples? @Mauin @arturbosch