search

dmy / elm-doc-preview

Elm offline documentation previewer
https://www.npmjs.com/package/elm-doc-preview
Other
128 stars 15 forks source link

Provide a way to expose all modules in an application #36

Open Kurren123 opened 4 years ago

Kurren123 commented 4 years ago

This is an awesome tool. If I have a huge elm application it can help me understand the project much easier, so I thank you for this.

If there are many modules in an application, it can be a pain adding these to exposed modules and maintaining this list whenever modules are added/removed. All I really want to do is browse all modules in source-directories specified in the elm.json. Would it be possible for this to be the default behaviour when no elm-application.json is present, rather than reporting an error?

Otherwise I’m happy for this behaviour to be a switch in the elm-application.json.

Cheers

rlefevre commented 4 years ago

I like this. The user experience would be better if the tool was working on any application without modification.

Actually, it could use all the modules found in source directories if exposed-modules is not provided (making elm-application.json optional) but it could even optionally stub itself empty documentation for undocumented exposed symbols during the current ports stubbing phase 🤔

This would allow to have by default all the signatures by module in any application. Of course, the behavior for packages would be unchanged.

Also a strict mode flag could be added to let the user list the modules and add documentation. This could be useful for CI checks.

Let me think about it for the next release.

Kurren123 commented 4 years ago

@rlefevre brilliant! Would you like any help?

rlefevre commented 4 years ago

@Kurren123 Sure! If you want to give a try at the PR, go ahead! I'm on slack (@dmy) if you have issues.

rlefevre commented 4 years ago

@Kurren123 Let's make two different PRs, one that that adds the feature you propose, the other one stubbing documentation with the -s, --strict option.

Kurren123 commented 4 years ago

I was also thinking, a nice default for the name would be user_name/dir where dir is the name of the directory containing the elm.json file, as I think this directory is usually a kind of project name.

rlefevre commented 4 years ago

@Kurren123 The potential issue with that is that sometimes the elm app is in a sub-directory of the project. For example, for one of my Elixir/Phoenix app, the elm application is in assets/elm, so the application would be named my/elm :thinking:

Let's discuss this in another issue if you want to.

Kurren123 commented 4 years ago

Ah okay, no worries. I’m just happy if I don’t need to maintain a list of exposed modules

rlefevre commented 4 years ago

@Kurren123 Feel free to open another issue, maybe there is a better solution.

Another issue is that there are a lot more restrictions on package names that directory names (and the application is transformed to a package before generating the documentation). A lot of characters are forbidden, and a few more rules.