Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merge with elm-docstyle? #66

Open
mristin opened this issue Oct 24, 2019 · 5 comments
Open

Merge with elm-docstyle? #66

mristin opened this issue Oct 24, 2019 · 5 comments

Comments

@mristin
Copy link

mristin commented Oct 24, 2019

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
Copy link
Owner

ento commented Oct 30, 2019

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
Copy link
Author

mristin commented Oct 30, 2019

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
Copy link
Owner

ento commented Oct 30, 2019

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
Copy link

@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
Copy link
Owner

ento commented Oct 31, 2019

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants