The request for a better error message and better documentation
- Dominant language
- Stylus
- Stars
- 719
- Forks
- 1.3k
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 9
Description
## For feature request
I'm a plugin/theme author and I appreciate your excellent work on static blogging.
But I find that both usage and API doc hosted on https://hexo.io are very unclear. Due to the dynamic-typed nature of Javascript, I can find little useful information on listed API function signature without being fully documented: I have no idea what argument I should pass, what type this variable is, what property this argument has, what I should return in callback.
Also the examples provided by doc are trivial and not very helpful. I have to dig into source code or program with the power of `console.log`, to get it work.
As for the error output, once I did something wrong I can only get an exception with little useful message thrown from a deeeeeeeeeep `Promise` async call stack. If the error occurs in post rendering I can get some feedback like which line of which file (sometimes not), but I can only get `unknown error` if error occurs in script/plugin execution.
Probably I'm not able to improve error log, but I'm glad to help improving the docs. Where can I start?
中文版:
我是一个Hexo的主题和插件作者,非常感谢你们打造的博客系统。
但是我在深入的使用中发现了文档的一些问题,比如使用说明和API写的非常不清楚。由于Javascript是一门动态类型语言,所以如果不在文档中详细写明的话,从API的函数签名中我是基本找不到任何有用信息的:不知道该传入什么,不知道类型是什么,不知道属性有哪些,不知道回调该返回什么。
除此之外文档给出的例子也是,太简单,起不到什么作用。这时候就只能深入发掘源码,或者是基于`console.log`编程。
至于错误输出,只要一步做错了就只能得到抛出来的异常,一长串的调用栈,基本没有用的错误信息。如果错误是发生在帖子渲染阶段,我倒是能得到是哪个文件第几行的错误输出(也不是总有);如果错误发生在脚本/插件执行阶段,就只能得到一个`unknown error`。
错误输出我可能是帮不了什么,不过我是很愿意帮助改进文档的。请问该从哪里开始?
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.