Documentation for generic actions

moxley

I’m trying to understand how to define a generic action, following the documentation. A generic action has a run option that appears to be where the work is done. There is a code example available that shows what using run with an anonymous function looks like for a happy path. All good so far.

The documentation for the run option gives a type spec of (any, any -> any) | module | module. What is any, any, and any supposed to be? What does the module in the type spec need to define? There’s no explanation under the “Doc” for run.

At the top of the actions.action documentation, it says “For calling this action, see the Ash.Domain documentation.”. Following that link goes to a fairly sparse page that has no mention of custom actions.

Is there another place in the documentation that talks about generic actions in more detail?

9 comments

/ash #ash-actions

0 620 9

2024-11-14 14:17:16 UTC

Showing Posts 1 to 9

Show Best Posts
Show All (oldest first)
Show All (newest first)

barnabasJ

Ash Core Team

Here is the behaviour you need to implement Ash.Resource.Actions.Implementation — ash v3.29.3

This should be referenced somewhere in the generic actions doc. If you’d like you could PR that.

The types should also clarify what the (any, any → any) should be. The anonymous function doesn’t take options.

Post #1

moxley

Thank you. How do you return an error? The Ash.Resource.Actions.Implementation documentation only provides a spec of {:error, term()}.

Post #2

barnabasJ

Ash Core Team

The best thing to return there is either a built-in or custom exception.

But anything would potentially work and would be wrapped in an Ash.Error.Unknown exception.

Post #3

moxley

Thank you

Post #4

moxley

If you’d like you could PR that.

I’ve contributed documentation PRs to Ash before.

I’ve been using Ash for over a year in production now. The documentation has been a major pain point the entire time, every step of the way.

Ash’s documentation has been really, really, REALLY frustrating. It’s hard to hide that frustration as I ask question after question about how to use Ash on this forum. I’ve never had to ask questions on a forum to understand a software tool before, let alone ask a continuous string of questions over the course of a year. I still find myself asking after all this time, “should I tear Ash out of my application?”.

Are the maintainers aware of this, or is it just too big of a problem to address in the foreseeable future?

If I submitted a PR every time I ran into clearly missing documentation, I’d be spending all my time on writing documentation for the Ash Framework rather than on the software I’m using it for.

Post #5

moxley

Here are some suggestions for improving the documentation:

For documentation on topic A, if understanding of A requires familiarity with topic B, then mention, and provide a link, to topic B.
Fill in the type specs. No more any() or term().
Fill in empty spots where there should be text.

Post #6

zachdaniel

Creator of Ash

We are aware, and this is the next major item on the docket. All reference documentation on every package will be gone over, including ensuring every function has typespecs, every option to every function is documented, and cross links exist to relevant guides etc.

Post #7