New documentation for `purescript-halogen-select v1.0`

Inspired by this conversation:

I took some time to document Select now that it has a stable release. We already had an overview and module documentation, but I wanted to add some more tutorial-focused content as well as some explanation-focused content around some of the unfamiliar ideas in the library.

The documentation site is here:

A thorough, beginner-friendly tutorial on creating a dropdown is here:

A faster-paced, more advanced tutorial on creating a typeahead is here:

An explanation of using a free query in Halogen (contributed by @monoidmusician) is here:

If any of you folks give this a read and notice ways it can be improved (too much information? too little? typos?) I would appreciate the feedback!

In addition to writing this documentation, I’ve set up a continuous integration process that builds the documentation site, which is itself quite full-featured. I’ll soon write about this process as it’s quite easy to have a beautiful, functional docs site hosted on GitHub pages for your library.

The general idea is that by lowering the difficulty to set up a documentation project like this we can make it a little easier to get started documenting your own libraries.


Wow Thomas this is looking great! I can hear your tone coming through, especially with this :laughing:

Effect rows can be surprisingly finicky to get right

Yeah?? hehe won’t you be glad when Halogen is ready for 0.12 :wink:

Ok some bits of feedback:

  • Small detail: Writing useful item types info box needs a newline to get code highlighting
  • Lines 28-40 of Feedback are a little confusing in the formatting, maybe it would be a good idea to refactor some helpers into let/where bindings? In general it’s easy for Halogen code to get messy like that … small functions are good! (so I say after writing a run-on sentence)

In your Project Setup tutorial you write

return the next query

I realize that phrasing is used elsewhere, but I think it’s inaccurate … really it’s just returning whatever was trapped inside the Query, and most of the time that’s actually unit (in event handlers, etc.). The exceptions would be EventSources (which return Listening status) and when you’re actually querying a component with H.query and want useful information out of it (;

But I don’t want to make a big deal out of that. Honestly the documentation looks great to me :smiley:

These are great notes! Thank you.

Shoot! Halogen is already ready for 0.12, so I guess I can go ahead and remove all that stuff. I should have waited a week to write this :slight_smile:

Right. I’ll fix this.

On reflection I think you’re right. I didn’t want to spend too much time changing the shape of the code from section to section because I find it difficult to keep track of these sorts of changes when I read tutorials. We discussed this a little on Slack – code tutorials fall down often because you don’t see the entire file at once, just a small window onto a few lines of it, and so without that context it can be tough to keep track of what’s happening. I tried to stick with the minimal number of changes necessary to get the whole thing working, but in the code you’ve called out here, it becomes tough to follow such a dense function.

I’m going to refactor it into renderItem, renderContainer, renderInput as I usually do in my own code.

You’re right here as well. Early into learning Halogen I thought of it as returning the ‘next’ query, largely because of what you stated there: most of the time it’s actually unit, in which case the next query runs. However, we’ve used H.query often enough that I should have known better when writing this! I’ll fix this as well.

Thanks again for the feedback @monoidmusician


1 Like

What tasks can I do to contribute to a documentation project for PureScript?

@RathishB23 You might choose a few libraries that you are currently using and reach out to the owners or most frequent contributors to ask how you might best contribute documentation to that library. You’ll be helping yourself as a user as well as helping others!

As far as the documentation you contribute goes, I think that cookbook-style content is sorely missing – the kind that demonstrates how to use a library to accomplish some task, rather than documentation that simply describes the concepts in the library or summarizes a few functions. The documentation for select does this by walking through how to build a dropdown and a typeahead using the library.

For example, the Argonaut libraries could really use some examples of how to decode and encode different JSON structures.

1 Like