apiV1.executeToggleTaskDoneCommand does not modify the note [by design - add to the docs]

[ctrl-q]

⚠️ Check issue is valid.

• My request is about the Tasks plugin for Obsidian.

⚠️ Check that this issue hasn't been reported before.

• I searched previous Tasks plugin Bug Reports didn't find any similar reports.

Steps to reproduce

1. Open a note named Untitled
2. Paste in a task with the text - [ ] This is a task 📅 2024-04-24
3. Open the Obsidian Developer Tools Console
4. Run the following command:

app.plugins.plugins['obsidian-tasks-plugin'].apiV1.executeToggleTaskDoneCommand('- [ ] This is a task 📅 2024-04-24', 'Untitled')

Expected Behavior

The note should be updated with the task marked as completed

Current behaviour

The note is not updated

Which Operating Systems are you using?

• Android
• iPhone/iPad
• Linux
• macOS
• Windows

Obsidian Version

1.7.7

Tasks Plugin Version

7.14.0

Checks

• I have tried it with all other plugins disabled and the error still occurs

Possible solution

No response

[claremacrae]

You are correct, it does not modify the note.

My guess is that you have not found the documentation that explains how it works.
https://publish.obsidian.md/tasks/Advanced/Tasks+Api

[claremacrae]

The following request covers adding the ability for the API to modify an existing task line.

• Support editing existing tasks from the API #1945

Feel free to up-vote it and subscribe to it.

[ctrl-q]

You are correct, it does not modify the note.

My guess is that you have not found the documentation that explains how it works. https://publish.obsidian.md/tasks/Advanced/Tasks+Api

I did. The documentation mentions that it "Executes the 'Tasks: Toggle task done' command on the supplied line string".

I guess this is more of a documentation question at this point, then.

"Simulate" seems like a more accurate verb than "Execute" in this scenario.

The fact that the method requires the file path adds to the confusion. I can input any random string there and get the same result, regardless of whether or not the task exists in my vault, let alone in that path

[claremacrae]

Current behaviour

Ah - apologies, I misread which of the two functions you are using.

You are using the recently-added one, and yes, it does indeed take an existing task line.

The important bit in that documentation is that it returns the edited string:

Tasks has no idea where the line came from, and in fact this functionality was written by the maintainer of the Kanban plugin, where there will not even be a markdown-editing-view open.

So it is still the responsibility of the caller to write the line to the correct place in their file.

What are you trying to do?

I would normally expect Tasks plugin users to use one of the many built-in ways of toggle a task:

https://publish.obsidian.md/tasks/Editing/Toggling+and+Editing+Statuses

So what is your scenario? Why put the cursor on a line and run a plugin API instead?

[claremacrae]

Yes, the console output shows the returned result of the function, and it is the toggled task line:

[ctrl-q]

I use the Full Calendar plugin to display my tasks. I can provide a callback that is called when I check the task from my calendar, allowing me to actually check it in my note.

I'll just wrap the executeToggleTaskDoneCommand result in a app.vault.process now that I know it doesn't actually modify the file. The documentation led me to believe it did

[claremacrae]

Do you have any suggestions for improvements to the wording of the documentation?

[ctrl-q]

It's rather subjective, but I might go with:

"Simulates the 'Tasks: Toggle task done' command on the supplied line string. It returns a string representing the task if it had been toggled, updated according to a user's preferences, accounting for recurrence rules and completed status."

[claremacrae]

I've removed the bug label - and added a documentation label, to remind me to clarify the documentation.