RealyUniqueName
commented
5 years ago Hi. Thanks for such a detailed message. Yes, contributors worry about poor API documentation. But until recently we didn't have enough manpower to continue improving the compiler AND write docs. Language design, compiler and bugfixes for existing users were more important (that's my personal opinion). And now the top priority is Haxe 4 final release. Hopefully after that we will be able to dedicate some time to work on API docs. Also, PRs are always welcome ;)
cancerberoSgx
Simn
haxe.io types API docs is poor or non existing. And is critical that users understand exactly what these types represent, in terms of POSIX / C since there are names not familiar in that language (which is the common language to document IO types in most platforms). For example Bytes, which doesn't have any description and is very important is a name unfamiliar in POSIX/C and have considerable implementation. Also *Data types that although representing native objects should be described in terms of C and if possible or if native types are different, details some native implementations too. It's more important that users have clear understanding than exposing internal information. I would write something like fro example.:
I strongly recommend to mention posix / C names if there is a straight relationship. In case different types are used on each target don't hesitate to name those too. Don't use redundant names like "native" or "array" or "int", be precise here. It's more important that users have clear understanding than exposing internal information in this case. Users micro optimizing performance that needs these details should be familiar with C / POSIX terminology, even those targeting the browser.
For example ,( being new to haxe ) I would write the following to describe BytesData
"It represents a native array of bytes which in general are stored as 8 bit unsigned integers, (integers in 0-255). Each target uses the optimal type tto access a byte array. If supported, ArrayBuffer or similar structure will be used or in lower level languages like C++ a plain old unsigned short[]. For example example in C++ an unsigned short[] is used while, in JavaScript and or python ArrayBuffer and python.ArrayBuffer are used, respectively. " ( I would even mention every native type here.
And a opinion: as somebody from the outside it surprised me to see such awesome compiler with so little API docs on this regard being this a critical area for docs, and since haxe don't use familiar names for io types. This gives a bad impression and almost could seem un respectful seeing unfamiliar names and implementations (which is not bad) with almost not existing apidos in such critical are like haxe.io. Personally If it weren't for some unique features of the compiler, this alone would be enough for me to stop using haxe (and if there were an alternative I would be researching already).
The manual is nice, but the api docs and in particular the core types and std give a very very bad impression. Specially when is not a hard / time consuming task (I bet people designing this packages can document haxe.io in a day or two-
Another opinion, besides driving away users, the platform is showing a bad example to users - if you explore haxelib library/API like projects one can see that is a common practice not to have any APIdocs and also not deliver any basic snippet in the readme or examples. Often the only resource are tests, if any. Several not even a readme. From my point of view is clear that is a common pattern in the community. (there are although a couple of libraries like lime and openfl that have excellent documentation compared with documentation the platform's they are built on top of which is embarrassing since they use the same documentation generator technologies promoted by the platform I think)
And a third one, that also worries me is that there is no issue or plan to work on this here (only an issue in the manual - https://github.com/HaxeFoundation/HaxeManual/issues/16l). ? Or I'm missing something or being dump to not figure it out something obvious that doesn't need any docs, like inferring what a Bytes instance is exactly or haxe users are not worried or just resigned or get used to this situation?
The only workaround I found was looking directly at haxe.io source code - it's not a blocker for me but totally unexpected from a platform and non-serious for users who are deciding to invest time in learning a technology to build software which is a very important decision for devs
This is just a feedback but it's what is happening to me now and take it from somebody who would expect differently, had great impressions from other parts of the platform and is underlying something that seems basic, very notable for developers with curiosity and experience in other open osurce platforms, and cheap to solve .And is not that haxe is a very new project so there wasn't time to plan/push this.
Seriously, very little work could boost quality and promotion of this platform! (If I had more experience , let's say 6 month os using it I would PR with these on my first opportunity - in other platforms this could be seen as an opportunity to become a contributor... what's going on?
Could somebody please just tell me if this also worries other contributors or owners, if there is a plan or be sincere as is not a priority for the project?
Thanks and sorry for the long mail but I feel this really huts the platform