Dhall-docs cli utility

#21

Hi, just digesting all your input

That’s what actually I wrote on my proposal I think. But I’d really like to add on records. If that gets difficult, a workaround will be for people to put the relevant doc for each record field on their module header or let-binding.

Thank you for noticing that and yes, I should try to make dhocs (henceforth I’m gonna use that name @lisael) in a way that it just doesn’t takes comments and outputs HTML, but to do this kind of things so dhall users don’t repeat themselves and without creating a tool that it’s hard to use, to create a haddock without the bad things of haddock).

And I don’t have any problem working on that after GSOC project (of course, if I have time to do so). I mean, I don’t want to just work on the project these 3 months and just say goodbye after it. I’d like to keep contributing later, I’m liking this whole project you’ve done.

Now, I’d like to thank all of your comments about this and ask you to not stop. I’m currently designing some simple mockups about what I think to be the front-end of the HTML output, but I’m open to any other suggestion or idea. I’ll also send here the result of my mockups so you can give me your thoughts about it as well.

1 Like
#22

Just a thought, how about you make it output a dhall expression which can then be converted to HTML or Markdown or manpages or whatever in a second step.

#23

That’s an interesting idea. If you take it another step forward (or backward, against the data flow) you might ask why not make the original annotations Dhall expressions rather than comments:

  • the annotation would not change the type of the expression,
  • it would be stripped away by destructive operations such as +, *, or ==,
  • a lambda would preserve it,
  • record merges would preserve the field annotations.

As an analogy, think of the semi-standard <?> parser combinator.

2 Likes
#24

@Profpatsch I like the idea and it could simplify a lot of things! I think it goes by the hand from @sjakobi comment on extending Dhall.Core.Expr a little.

@blamario regarding your last post I understand what you’re looking at and it looks really clever and it could simplify a lot of things. I’d like to give it a try and see how it goes.

#25

Hi all! I have some news about the tool so far.

  • We end up using dhall-docs instead of dhocs as @lisael suggested. The reason is that described in #1833 (comment)
  • I’ve made some progress, but the tool is far from actually usable yet. See this list of PRs to have a notion of what is actually done.

Now I’d like to introduce some comments and regards we end up having about the structure of the documentation

(context #1863 (comment)) We’ll need to distinguish between documentation comments and internal comments. In that thread we agreed we’ll use {-| and -- |.

(context #1868) To ease documentation writing, we’ll use commonmark as a base. mmark is a haskell package that let us parse commonmark and produce html. Now an issue is that commonmark is really sensitive to indentation.
For example, if you write the following markdown:

foo
bar
baz

it will render 3 <p> html elements, but the following:

foo
bar
    baz

will render 2 <p> for foo and bar and render a <code> for baz. That feature is indented-codeblocks

When we write documentation in a header, one might write something like this:

{-| foo
    bar
    baz
-}

One would expect that it renders 3 <p>. Currently, dhall-docs is just removing the {-| and -}, so the text ends being:

foo
    bar
    baz

and it renders <code> blocks, instead of what the user might thought at the beginning: 3 <p>.

We can’t just strip each line because there are some common markdown features (like nested list items) that needs the indentation, so it looks like we need an explicit way to define it.

In that thread, we proposed using | to solve it.

{-| foo
  | bar
  | baz
-}

Now is clear that indentation is the same, and its easier to process. This is similar to javadoc, where each line starts with *; or rustdoc, where each line starts with ///.

I’d like to read your thoughts about this so far and your experiences with other language doc generators.

1 Like