Merge with elm-docstyle?

[mristin]

Hi!
Since elm-docstyle supports --validate flag, would you consider merging that functionality with elm-docstyle? (https://github.com/Parquery/elm-docstyle)

If so, I would like to translate it to Python and submit a PR.

Thanks for your feedback!

[ento]

By merging, do you mean: when calling elm-doc with --validate, elm-doc will call elm-docstyle under the hood?

Also, what do you mean by translating?

Taking a quick look at elm-docstyle, my concerns would be:

1. Currently elm-doc uses the elm binary itself to validate if documentation can be generated without an error. Does/can elm-docstyle have a test-suite (maybe property-based testing?) to verify that it correctly detects errors whenever elm itself would raise an error?
2. This is more of a minor thing: can elm-docstyle take elm.json as an input and allow excluding source directories through the config file, or take multiple directories as an input? elm-doc reads elm.json to figure out which directories to check, and it'd be convenient to be able to call elm-docstyle just once when there are multiple source directories.

elm-doc has been meant to be a temporary solution until something like elm-docstyle comes along, so I'm looking forward to what comes of this.

[mristin]

Hi @ento,

By merging, do you mean: when calling elm-doc with --validate, elm-doc will call elm-docstyle under the hood?

Sorry for the misunderstanding, my message was too terse.

Elm-docstyle is written in Elm, while elm-doc is written in Python. I thought to translate elm-docstyle to Python and implement its functionality completely into elm-doc.

Currently elm-doc uses the elm binary itself to validate if documentation can be generated without an error. Does/can elm-docstyle have a test-suite (maybe property-based testing?) to verify that it correctly detects errors whenever elm itself would raise an error?

If I remember correctly, we do not do that. @TeodoroFilippini could you please confirm?

This is more of a minor thing: can elm-docstyle take elm.json as an input and allow excluding source directories through the config file, or take multiple directories as an input?

It has its own configuration file. Since the code would need to be translated anyhow, we can define what additional functionality would be implemented in elm-doc.

[ento]

Elm-docstyle is written in Elm, while elm-doc is written in Python. I thought to translate elm-docstyle to Python and implement its functionality completely into elm-doc.

Ah, okay. To further clarify, elm-docstyle's Elm implementation will no longer be maintained, or is the intention to keep updating both implementations? In any case, there'll be pros and cons to the alternative ways of how to go about this, and I don't feel like I have the full picture yet to be able to decide what's best.

[TeodoroFilippini]

@mristin we do not have a test suite for detecting Elm compilation errors, since elm-docstyle uses elm-syntax to parse the Elm source code, which in turn raises an error whenever the compiler would.

[ento]

The errors the Elm compiler may catch range from syntax errors to documentation errors such as those listed here. I assume documentation errors are not caught by elm-syntax.

Since elm-doc's purpose is to generate browsable documentation, and as it currently uses the Elm compiler to do so, my interest is in if elm-docstyle's validation mode has guarantee that it will catch all (documentation) errors that the Elm compiler will catch and abort (or if it's in the interest of the project to have such a guarantee).

I see a few alternative paths:

1. Use both the Elm compiler and elm-docstyle's finer-grained checks for validation, use Elm compiler for generating docs
2. Use elm-docstyle's finer-grained checks for validation, add tests to elm-docstyle for the aforementioned guarantee, use Elm compiler for generating docs
3. Use elm-docstyle's finer-grained checks for validation, add the capability to emit docs.json to elm-docstyle (i.e. stop using Elm compiler altogether)

Whether to implement these in Elm or Python is an orthogonal decision.

Any thoughts / preferences?