clarity-lang / overview Goto Github PK

Could consider adding a link to clarity docs from the README for better discoverability

As we want contracts to be read and understood as easy as possible, it would be nice to support an improved documentation system for Clarity. Think pydoc or something similar.

Proposal for a very simple and effective doc standard:

• comments are still ;;
• use markdown in comments
• the comment at the top is special: what is the contract about?
• comments above constants / variables / maps are special: what do they store?
• comments below a (define-public or any other function is special: what is the function about?

A simple parser can then generate an HTML or markdown document that is structured:

• Contract name (how?)
• Description
• Each constant / variable / map with a description
• All functions with a description

All other comments can be read by drilling down inside functions.

In the Clarity starter turorial in here "https://github.com/clarity-lang/overview/blob/master/tutorial-hello-world.md", where you need to type the command "cat test/hello-world.ts", the "cat" is not recognized as a comand in windows shell!...What needs to be done in order to run it on windows?

I have node v15.12.0.

When I try npm init clarity-starter, I end up getting:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: [email protected]
npm ERR! Found: @blockstack/[email protected]
npm ERR! node_modules/@blockstack/clarity-native-bin
npm ERR!   @blockstack/clarity-native-bin@"^0.3.12" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer @blockstack/clarity-native-bin@"^0.1.10-alpha.0" from @blockstack/[email protected]
npm ERR! node_modules/@blockstack/clarity
npm ERR!   @blockstack/clarity@"^0.3.12" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

I'm able to run npm init --legacy-peer-deps clarity-starter successfully, however npm test always outputs: error: unknown option '--extension'

I had to run this on Linux to make it work.

The CAT command is not recognized by Windows.
The npm test didn't work either in Windows.

Maybe suggesting to use any environment except Windows?

Clarity is a decidable language. A programming language is decidable if you can know, with certainty, from the code itself what the program will do.

I think this statement should be modified, as it is easy to misunderstand. The only thing removing recursion from a language does is enable the evaluation of worst-case time and space bounds. It does not improve any other aspect of static analysis and program verification. This statement as it stands makes it seem as if any question about program execution is algorithmically decidable if the program is written in a decidable language, which is not the case.
If a counter were to be attached to every recursive call in a Turing-complete language, one could also limit recursion as to form a decidable sublanguage. This does not help with human-comprehensible properties one would like to state about the programs.

As a secondary point, there are supersets of decidable languages that are clearly "knowable as to what the program will do" if decidable languages are. Adding the program with a single empty loop to the language is still "understandable to humans", yet adds non-terminating programs to it.