Automate docs on GitHub

[​ ​man]

I suppose you don't want to publish Automate code on GitHub, but my question is if you would like to publish Docs? There were a few times that I wanted to correct / improve Docs (like recent Wi-Fi connected  block security output) and the only way is to ask you. IMO the Docs would profit from it :) (Of course I assume you still would like each pull request to be accepted by you, which is natural). 

[Henrik "The Developer" Lindqvist]

I'm hesitant of open-sourcing the documentation for what is expect to be very little help, if any. But i'll consider it.

[​ ​man]

I understand, it's all up to you :) I thought that open-sourcing the Docs would allow helping you (and other users) and not introduce any threats (since Docs are already public). Although I'm not a professional developer and may be wrong. 

[Ricardo “Rudxain” Fernández Serrata]

Speaking of that, I think AM would benefit from having a formal specification, even if there's only 1 implementation. There are some functions which have undocumented behavior, and there's fns and blocks which may throw undocumented exceptions. I understand that comprehensive docs are hard to achieve, it's also hard for me (look at my `xorsum` GitHub repo, lol)

[Henrik "The Developer" Lindqvist]

Agreed, but it would be an huge task, and nearly impossible for blocks, since those rely on the Android API which is too fragmented, unstable, and just as poorly documented.

[​ ​man]

What pushed me to start this topic is that there are often questions here (which you answer and it takes your time) that can be avoided by improving the docs. Many of your answers here inlude additional information about blocks or fns, tips&tricks or links to Android API that talk about a wider (or more specific) topic – this can (and often should) be added to docs.

I know that improving the app is more important than improving the docs; however improving the docs is less dangerous than improving the app, sou you may at least allow others help you. We all have our lives (usually not related to coding) so it will not be common, but may happen.

[Henrik "The Developer" Lindqvist]

I do try to include things that get asked a lot, a problem is that many users don't even read the documentation, and instead choose to post a question.

Writing the words in the documentation isn't what's time consuming, it's the reproducing of the issue, or find a solution for whatever they're asking. If i were to allow others to edit the documentation, i'd still have to do that, i.e. review the commits, verify the edits.

[​ ​man]

I don't want to create a new thread, I just want to report a typo in docs: https://llamalab.com/automate/doc/expression.html#logical_operators. It is (quote, bold mine):

Logical NOT !

A unary prefix operator that returns 1 if the operand evaluate to true, otherwise 0 is returned; !3 returns 0.

Should be:

Logical NOT !

A unary prefix operator that returns 1 if the operand evaluate to false, otherwise 0 is returned; !3 returns 0.

[Henrik "The Developer" Lindqvist]

Thanks for reporting. Fixed for next release.

[​ ​man]

Variables take block description says:
"The queue has a capacity of at least 128 value sets, when full the giver fiber will fail."

Didn't you mean "at most"? 

[Henrik "The Developer" Lindqvist]

Hmm, indeed a typo. However the limit is much larger, as it scales with the fiber scheduler timer/iteration limits, but i'll leave it low in the doc so users are aware that a fiber shouldn't "give" too much.

[​ ​man]

https://llamalab.com/automate/doc/block/variable_assign.html In the 1st sentence the "variable" link should point to https://llamalab.com/automate/doc/variable.html

[Henrik "The Developer" Lindqvist]

Indeed, thanks for reporting, i'll fix.

[​ ​man]

No problem, I'll come back here in case of any bugs or typos in docs ;)

[MyNameisBob (Pluto)]

This thread makes me wonder if there's something the community can help with so you are able to focus on the app and your other projects. All in all though its up to you, but I'm willing to bet quite a few people would be happy to help out even if its just a typo fix in the docs.

[Henrik "The Developer" Lindqvist]

As said, there's little difference in the amount of work of actually fixing the typo myself vs reviewing a commit of someone else having done it.

[MyNameisBob (Pluto)]

Yeah that's a good point.

[​ ​man]

It would be nice if "round" function description contained information if half rounds up or down. AFAIK various programming languages can treat this differently. 

[Henrik "The Developer" Lindqvist]

I'll consider it. But i'll probably do that when also implementing an separate rint function, or let that replace the current replace round, and if that would break existing flow then need an "compatibility" option implementation.

[​ ​man]

Could you update copy function docs with your explanation of shallow/deep copy from here?

A "shallow copy" only duplicates the containing (root level) array or dictionary, not its (nested child) values.

A "deep copy" also duplicates every element value in an array and/or entry value in a dictionary, and any nested (child) values therein, and so on.

[Henrik "The Developer" Lindqvist]

Will do.