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

[thomashoneyman]

Inspired by this conversation:

Ideas for improving PS documentation?

Phil has said that he’d like the PureScript language to “stabilize” for the next year or so, and he’d like the documentation around the project to catch up. I feel like the documentation the PS community produces is slow and steady, which is great, but I feel like we can improve quite a bit! I’m curious to find ways in which we can get PureScripters to contribute documentation towards various parts of the ecosystem. Perhaps a more productive start to this conversation is: What barriers do peop…

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:
https://citizennet.github.io/purescript-halogen-select/

A thorough, beginner-friendly tutorial on creating a dropdown is here:
https://citizennet.github.io/purescript-halogen-select/tutorials/dropdown/

A faster-paced, more advanced tutorial on creating a typeahead is here:
https://citizennet.github.io/purescript-halogen-select/tutorials/typeahead/

An explanation of using a free query in Halogen (contributed by @monoidmusician) is here:
https://citizennet.github.io/purescript-halogen-select/concepts/understanding-free-queries/

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.

[monoidmusician]

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

Effect rows can be surprisingly finicky to get right

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

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

[thomashoneyman]

These are great notes! Thank you.

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

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

Small detail: Writing useful item types info box needs a newline to get code highlighting

Right. I’ll fix this.

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?

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.

In your Project Setup tutorial you write

return the next query

I realize that phrasing is used elsewhere, but I think it’s inaccurate

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

[thomashoneyman]

Updated!

Updates to documentation