Hello everyone!
I’m Germán and I was selected on GSoC program to contribute on dhall, specifically on dhall-haskell implementation. My project details can be found here. @Gabriel439, @sjakobi and @Profpatsch are my mentors
In summary, the goal of the project is to develop a dhall-docs cli utility that will take up some dhall files or packages and output an HTML containing actual documentation. Similar to other tools in other programming languages like haddock on haskell or rustdoc on rust. After generating HTML, I’ll implement markdown support as well.
I’d like to read your comments about what would you expect from the tool, like syntax and general usage.
The features that generated HTML will have are the following:
- The actual documentation extracted from source code comments;
- Browsing the original source code;
- Type on hover;
- Jump to definition
So first thing that I need to do is to design a grammar in order to successfully extract and manipulate source code comments. I was thinking to go with something markdown based. To bold a phrase, we can use markdown bold syntax. To italic a phrase, we can use markdown italic syntax and so on.
I don’t know if comments should have a marker like haddock’s one (-- | or {- |) or javadoc one (/** instead of /*) for example. I’d say yes since not all comments could be for documentation purposes. I’ll keep up with haddock’s one for the rest of the post.
I’ll start with file headers. For example,
{-| My *awesome* function. This does _everything_ you want.
You should also see `myOtherFun` to see what it does
**NOTE**: this is something really important that
you need to be careful about
-}
let f = 1 in f
Name references can be made using backtics. In the HTML output, it will show itself using a console style and as a link that you can click and go to that specific html page.
If the name reference is a link, then it can go to that link. The project should not make any assumption yet about where are these docs going to be deployed and it may be in different places.
If the name reference is a relative path to another location, it could redirect to that page.
Previous example put their docs in the header part of the file and scope of my project is aimed to start processing only that part, but as an enhancement I’d like to extend these doc annotations to other places, like record fields on types:
{-| Create a world citizen
You can customize their ages and stuff
-}
let Person
: Type
= { name : Text -- | Name of the perseo
, dob: Date -- | Date of birth
}
on union types
let Strategy: Type =
< Full -- | Do full analysis
| Partial -- | Do partial analysis. As `Strategy.Full`, but without A*
>
on function arguments
{-|
Concatenate a `List` of `List`s into a single `List`
-}
let concat
: ∀(a : Type) → List (List a) → List a
= λ(a : Type) → -- | Element types
λ(xss : List (List a)) → -- | List to concat into a single one
...
and any other places that you think it could be helpful to.
Please, let me know what you think about this and issues you see. I’m not very experienced on dhall and probably I’m missing something. Thanks in advance
