API to get list of example and short description

[lymslive]

Hello, Is ther any API to fetch the list of all available examples as the online IDE (http://wenyan-lang.lingdong.works/ide.html)? Then user have way to load example directly in offline IDE/editor(plugin).

The Snippet Site as #472 can also try to provide such API.

1. qeury list of code snippet/example, and short decription/remark
2. get the contenet of specific snippet/exmple, maybe a simple url

To get short remark for an example/snippet, there is need to specify a normalized conversion of comment in wenyan-lang code. Such conversion may also be virtal for stdlib auto-documentation.

Now we have there keyword for comment, 疏, 注, 批, then I think up three type/level comment:

1. file level (script/module level), remark for the whole file
2. block level, doc for important compenent, function(术), class, etc
3. statement level, tips for some tricky statement or algorithm

Then discusstion which keyword match which comment level. In my option, 疏 for file level, 注 for block level, 批 for statement level.

The native meaning of these three keyword refer to https://github.com/LingDong-/wenyan-lang/pull/35 . But we can redifine it for technique purpose.

Then back to the problem in this issue, the short remark accompany with list of example/snippet may be extracted from the first line of file level comment.

[lymslive]

Later, considerate the native meaning of 疏 is further comment of 注, I think up another suggestion.

• 注 used for simple remark for block, normally a short single sentense, or just more descriptive name.
• 疏 used for detail explain of this block, for 术 main describ it's parameter and return value.
• 批 still used for statement level tips.

However, comment is not forced syntax, this plan may seam rigid, user should remember one 注 followed by several 疏. While in previous plan seams has more freedom, in most time just use 注, only optional one 疏 in head of file.

Anyway, we just need a standar, then we can develop tool chian based on it.

[LingDong-]

Hi @lymslive , thanks for bringing this up!

List of examples can be fetched with a POST request to wenyan-snippets.glitch.me/all. Specific examples can be fetched with wenyan-snippets.glitch.me/api?id=123.

You can read more about the snippets site at #472

In my opinion, 注 should be universally used to explain code. 疏 should be used to supplement 注 where necessary. 批 should only be used as remarks, thoughts, or reviews and not for explaining implementation.

[lymslive]

Hi @LingDong-

1. I've try curl command to query the snippet site, can GET a specific id, but fail to POST to /all, yet can GET /all. But the output is a long json array, that may not what I mean exactlly. I mean first get a list of less (meta) information, mainly title/name and short description etc, not full code, then user can decide to get a specific code snippet interested. When the snippet site is filled with many code spippet, all will be to much data.

2. The example I mentioned is another thing from snippet site, that are the example in https://github.com/LingDong-/wenyan-lang/tree/master/examples and http://wenyan-lang.lingdong.works/ide.html . I think it make sence to maitenance both, one for smaller official example, another for larger user custom snippet.

I've noticed there is a json file tools/examples_info.js that seams be edited manually? What I suggestion is to write a short comment on top of the example file, then tools/examples_info.js and relative .md doc may auto-generated, like stdlib.

[LingDong-]

@lymslive Good suggestion, these API's could be quite handy. Thanks for bringing this up!

As for examples_info.js, maybe it is better to keep it that way. Self-documentation is nice, but the examples are for the new comers to read, and magical comments tend to add noise. I know it is currently just a title and some links, but in the future we might want to add more metadata in examples_info.js. Moreover, it is really same amount of work to write the documentation in either places.

Thanks!

[lymslive]

@LingDong- I understand you concern about examples_info.js

I've integrated Example and Snippet command into vim plugin vim-wenyan which forked from voldikss

However when I test in my home computer

1. get /all from snippet site is a bit slow, waiting for several seconds, may due to poor net beside larger data transfer.
2. I also fail to visit https://raw.githubusercontent.com/LingDong-/wenyan-lang/master/tools/examples_info.js to get examples_info.js. So I work around it, now required clone down to local folder and tell vim-plugin where.