search

ngs-lang / ngs

Next Generation Shell (NGS)
https://ngs-lang.org/
GNU General Public License v3.0
1.4k stars 43 forks source link

Feedback on documentation #616

Open MinmoTech opened 1 year ago

MinmoTech commented 1 year ago

Currently the tutorial is not as useful as it could be in my opinion :slightly_smiling_face: I would remove everything about AWS in the tutorial and put it in a separate document called something like Cool ngs features.

The tutorial is almost completely lacking examples of the commands syntax, which would be super useful to see as a beginner. And while piping into ngs is very cool, calling ngs scripts in file would probably be easier to learn with in the tutorial, especially since currently the lines are sometimes longer than the width my screen can display.

Furthermore while the Language Description page has most information one could ask for, it's very hard to search through it as it doesn't have a table of contents. I'm currently using https://github.com/skipto-landmarks-headings/browser-extension to generate a fake TOC.

ilyash-b commented 1 year ago

Thanks for the feedback! I need to process it.

MinmoTech commented 1 year ago

Being able to search for methods by their argument types in the global namespace would also be super useful! :)

ilyash-b commented 1 year ago

Being able to search for methods by their argument types in the global namespace would also be super useful! :)

The closest thing right now is when you navigate to a type, you can see all the methods that can have the current type as any of the arguments. Example: https://ngs-lang.org/doc/latest/generated/Eachable1.html

It's hard for me to imagine how it should work for multiple arguments. How do you see it? Provide (in search) ordered or unordered types of arguments? I'm not sure how that would be used. Can give an example?

MinmoTech commented 1 year ago

Oh, it seems I just did not navigate the generated docs correctly before.

I previously thought that primitive types are not available as Int is available as a child of Num and I sometimes didn't find a method as it was available for Any instead of the type I was looking for.

So I believe the current structure is fine, maybe a section in the tutorial on how to navigate to documentation would be good though. :slightly_smiling_face: