Haxe, NME, Documentation

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Haxe, NME, Documentation

Chman
Hi,

I'm a long time lurker on this list (via http://haxe.1354130.n2.nabble.com/) but this is my first "contribution" to it. I really like Haxe, especially with NME. I'm currently putting the finishing touches on my current AS3 project and I'll fully switch to Haxe in the next few weeks, with Flash and iOS export in mind.

Haxe is gaining a lot of good reputation those days, more and more people use it and NME is getting to a point where it's finally a viable solution to make multiplatform 2D games. But it's missing something IMO...

Good documentation.

I mean, look at this : http://haxe.org/doc. It's a mess. But it's not that bad. What's bad though, it's the API documentation (http://haxe.org/api). Could Haxe switch to a proper documentation tool like javadoc or asdoc ? Browsing the API would be so much easier, cleaner, and organized. More important, the same tool (and thus the same documentation style) could be used for other Haxe libs, like NME which doesn't have API documentation at the moment and really needs some, so we would have some kind of homogenized documentation system.

I understand that writing tutorials, extensive manuals etc is a time consuming process, but generating a good API reference is one of the most important thing for a programming language. It's the bare minimum. Clean, organized documentation.

Because of that (and the way the website is layed out), Haxe really looks like a hacky programming language and I know it DOES scare off some people.

I also think you should dump the current forum and switch to something more practical, like vBulletin/SMF/phpBB, something people are used to, with a good search engine. The same goes for Haxenme.org : the website is nice, tutorials and documentation are coming slowly but nicely, but the forum is not very user-friendly. Too much space wasted on topic listing, and no search engine whatsoever.

Finally, I feel like something should be done with lib.haxe.org but I honestly don't know what. It's a bit raw.

I think the whole Haxe website should be organized differently and should try to be a central point for the whole Haxe community, because this community is very sparse, so are the documentation and various libs. Right now, when you're looking for something, you need to google it and browse blog pages, googlecode wikis and such, that's a pity.

There's this great language, this awesome and helpful community, but it's scattered around the web and I can tell you it's really scary for newcomers and companies.

How about redesigning and reorganizing Haxe.org ?

I know this is a lot of work and would take some time to get it right (time I don't even have myself, although I'd love to help here), but I think it's really necessary for Haxe and its community.

- Tom
Reply | Threaded
Open this post in threaded view
|

Re: Haxe, NME, Documentation

Nicolas Cannasse
Le 12/10/2011 11:08, Chman a écrit :
> How about redesigning and reorganizing Haxe.org ?
>
> I know this is a lot of work and would take some time to get it right (time
> I don't even have myself, although I'd love to help here), but I think it's
> really necessary for Haxe and its community.

Free time and enough willpower are the key.

Any volunteers ?

The current haxe.org sources are available here :
https://svn.motion-twin.com/hxwiki/v2/

And for lib.haxe.org :
http://haxe.googlecode.com/svn/trunk/std/tools/haxelib

As for the documentation, it's extracted by the compiler for sources and
then synced to the wiki using the following code :
https://svn.motion-twin.com/hxwiki/v2/src/tools/ApiSync.hx
The documentation if is was completed on the wiki is kept untouched.

We should have - hopefully soon - a new haxe.org frontpage which will
explain/market a bit more what is haXe. This will not fix all the issues
you have explained.

Best,
Nicolas

--
haXe - an open source web programming language
http://haxe.org
Reply | Threaded
Open this post in threaded view
|

Re: Haxe, NME, Documentation

Michael Cann
In reply to this post by Chman
Personally I like how haXe is documented and prefer it over a javadoc view. Plus if there is something you dont fully understand from the docs provided you can always press F4 (from flash develop) and have a peek at the source.

However I do know what you mean by the "hackish" feel to it and the way it scares people off. This kind of relates to my post I made last night about the great worry of haXe & NME from an employers perspective.

As for your comments on the NME forum I agree that it could do with a little bit of polish but its perfectly serviceable and as its a free, open-source project I think its difficult to complain, it does the job just fine for now IMO.

As for lib.haxe.org I kind of like it. Its fast both in terms of navigability and performance. Perhaps it should have a little more information about what each project does, but then again who are we trying to target with lib.haxe.org, its not as if its the chrome extension webstore or something that targets end users, its for developers.

Personally im in two minds about this mailing list. On one side I like having all haxe discussion being forced on me (via mails), it means im constantly in touch with what is going on. On the other hand it is rather inaccessible for new users and searching it via google can be somewhat of a minefield at times. I know there is a forum for haXe however for it to become useful it needs people to use it rather than this list :P

On 12 October 2011 10:08, Chman <[hidden email]> wrote:
Hi,

I'm a long time lurker on this list (via http://haxe.1354130.n2.nabble.com/)
but this is my first "contribution" to it. I really like Haxe, especially
with NME. I'm currently putting the finishing touches on my current AS3
project and I'll fully switch to Haxe in the next few weeks, with Flash and
iOS export in mind.

Haxe is gaining a lot of good reputation those days, more and more people
use it and NME is getting to a point where it's finally a viable solution to
make multiplatform 2D games. But it's missing something IMO...

Good documentation.

I mean, look at this : http://haxe.org/doc. It's a mess. But it's not that
bad. What's bad though, it's the API documentation (http://haxe.org/api).
Could Haxe switch to a proper documentation tool like javadoc or asdoc ?
Browsing the API would be so much easier, cleaner, and organized. More
important, the same tool (and thus the same documentation style) could be
used for other Haxe libs, like NME which doesn't have API documentation at
the moment and really needs some, so we would have some kind of homogenized
documentation system.

I understand that writing tutorials, extensive manuals etc is a time
consuming process, but generating a good API reference is one of the most
important thing for a programming language. It's the bare minimum. Clean,
organized documentation.

Because of that (and the way the website is layed out), Haxe really looks
like a hacky programming language and I know it DOES scare off some people.

I also think you should dump the current forum and switch to something more
practical, like vBulletin/SMF/phpBB, something people are used to, with a
good search engine. The same goes for Haxenme.org : the website is nice,
tutorials and documentation are coming slowly but nicely, but the forum is
not very user-friendly. Too much space wasted on topic listing, and no
search engine whatsoever.

Finally, I feel like something should be done with lib.haxe.org but I
honestly don't know what. It's a bit raw.

I think the whole Haxe website should be organized differently and should
try to be a central point for the whole Haxe community, because this
community is very sparse, so are the documentation and various libs. Right
now, when you're looking for something, you need to google it and browse
blog pages, googlecode wikis and such, that's a pity.

There's this great language, this awesome and helpful community, but it's
scattered around the web and I can tell you it's really scary for newcomers
and companies.

How about redesigning and reorganizing Haxe.org ?

I know this is a lot of work and would take some time to get it right (time
I don't even have myself, although I'd love to help here), but I think it's
really necessary for Haxe and its community.

- Tom

--
View this message in context: http://haxe.1354130.n2.nabble.com/Haxe-NME-Documentation-tp6884131p6884131.html
Sent from the Haxe mailing list archive at Nabble.com.

--
haXe - an open source web programming language
http://haxe.org



--
Mike Cann
http://www.mikecann.co.uk/


--
haXe - an open source web programming language
http://haxe.org
Reply | Threaded
Open this post in threaded view
|

Re: Haxe, NME, Documentation

Chman
Michael Cann wrote
Personally I like how haXe is documented and prefer it over a javadoc view.
Plus if there is something you dont fully understand from the docs provided
you can always press F4 (from flash develop) and have a peek at the source.
Well, Javadoc/Asdoc have the advantages of being organized. You can clearly see what's a property, what's a method, what's inherited and what's not. For example, take a look at the BitmapData documentation :

Haxe : http://haxe.org/api/flash9/display/bitmapdata
AS3 : http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/display/BitmapData.html

The Asdoc version is really clean and easy to browse IMO. And I think the community would benefit from having something like that for Haxe.

Michael Cann wrote
As for your comments on the NME forum I agree that it could do with a little
bit of polish but its perfectly serviceable and as its a free, open-source
project I think its difficult to complain, it does the job just fine for now
IMO.
Oh, I'm not complaining, I love NME and I thank its authors for their hard work ! I'm just saying that the forum engine used on Haxenme.org feels hackish as well. Why do things differently when you can use something powerful and scalable like SMF with a custom theme ? Once again, it's just for the good of the community :)

- Tom
Reply | Threaded
Open this post in threaded view
|

Re: Haxe, NME, Documentation

Michael Baczynski-2
I would suggest using chxdoc - it's a wonderful tool written in haXe, fully customizable and besides
some minor quirks works great. I'm using it for documenting my library, see
http://www.polygonal.de/doc/ds/

On 12.10.2011 15:45, Chman wrote:

>
> Michael Cann wrote:
>>
>> Personally I like how haXe is documented and prefer it over a javadoc
>> view.
>> Plus if there is something you dont fully understand from the docs
>> provided
>> you can always press F4 (from flash develop) and have a peek at the
>> source.
>>
>
> Well, Javadoc/Asdoc have the advantages of being organized. You can clearly
> see what's a property, what's a method, what's inherited and what's not. For
> example, take a look at the BitmapData documentation :
>
> Haxe : http://haxe.org/api/flash9/display/bitmapdata
> AS3 :
> http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/display/BitmapData.html
>
> The Asdoc version is really clean and easy to browse IMO. And I think the
> community would benefit from having something like that for Haxe.
>
>
> Michael Cann wrote:
>>
>> As for your comments on the NME forum I agree that it could do with a
>> little
>> bit of polish but its perfectly serviceable and as its a free, open-source
>> project I think its difficult to complain, it does the job just fine for
>> now
>> IMO.
>>
>
> Oh, I'm not complaining, I love NME and I thank its authors for their hard
> work ! I'm just saying that the forum engine used on Haxenme.org feels
> hackish as well. Why do things differently when you can use something
> powerful and scalable like SMF with a custom theme ? Once again, it's just
> for the good of the community :)
>
> - Tom
>
> --
> View this message in context: http://haxe.1354130.n2.nabble.com/Haxe-NME-Documentation-tp6884131p6885047.html
> Sent from the Haxe mailing list archive at Nabble.com.
>


--
haXe - an open source web programming language
http://haxe.org
Reply | Threaded
Open this post in threaded view
|

Re: Haxe, NME, Documentation

David Peek-2
Michael,

I really love your library and use it on a daily basis when I need fast, documented and well tested utilities :) Thanks so much for sharing it!

Just noticed this in your docs:

x : Array<toArray3.T>


I wasn't aware of this syntax... is it a way to label your generics? Very useful :)

David

On 13/10/2011, at 2:02 AM, Michael Baczynski wrote:

I would suggest using chxdoc - it's a wonderful tool written in haXe, fully customizable and besides some minor quirks works great. I'm using it for documenting my library, see http://www.polygonal.de/doc/ds/

On 12.10.2011 15:45, Chman wrote:

Michael Cann wrote:

Personally I like how haXe is documented and prefer it over a javadoc
view.
Plus if there is something you dont fully understand from the docs
provided
you can always press F4 (from flash develop) and have a peek at the
source.


Well, Javadoc/Asdoc have the advantages of being organized. You can clearly
see what's a property, what's a method, what's inherited and what's not. For
example, take a look at the BitmapData documentation :

Haxe : http://haxe.org/api/flash9/display/bitmapdata
AS3 :
http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/display/BitmapData.html

The Asdoc version is really clean and easy to browse IMO. And I think the
community would benefit from having something like that for Haxe.


Michael Cann wrote:

As for your comments on the NME forum I agree that it could do with a
little
bit of polish but its perfectly serviceable and as its a free, open-source
project I think its difficult to complain, it does the job just fine for
now
IMO.


Oh, I'm not complaining, I love NME and I thank its authors for their hard
work ! I'm just saying that the forum engine used on Haxenme.org feels
hackish as well. Why do things differently when you can use something
powerful and scalable like SMF with a custom theme ? Once again, it's just
for the good of the community :)

- Tom

--
View this message in context: http://haxe.1354130.n2.nabble.com/Haxe-NME-Documentation-tp6884131p6885047.html
Sent from the Haxe mailing list archive at Nabble.com.



--
haXe - an open source web programming language
http://haxe.org


--
haXe - an open source web programming language
http://haxe.org
Reply | Threaded
Open this post in threaded view
|

Re: Haxe, NME, Documentation

Russell Weir
I'm glad that at least one project is using chxdoc (great template btw), and it probably is quirky now, since it's hard to keep up with Nicolas' progress.

I wrote chxdoc years ago in the hopes that we could start taking those steps towards getting more people to volunteer their time to contribute. Back then, there were far fewer people following haxe, so it was hard to get volunteers. We did start at least a couple of attempts at enhancing documentation, but life was always overwhelming the few volunteers there were.

It's nice to see that more people are asking. What it will take is at least 3-4 people to watch haxe SVN commits, and make sure things are documented. I've watched Nicolas code for years, and I can tell you two things: 1) he writes great code, quickly. 2) He doesn't have much time to type between the /* and */, and almost never uses any //'s. So, the early adopters of the language read the code, in the hopes that we could figure out what Nicolas was up to... and it worked, for the most part.

Nicolas was speaking about starting a haxe foundation in another thread, and that's likely what needs to evolve next, but that takes commitment from people other than just Nicolas, so when the time comes... volunteer, get involved, and keep at it.

As for chxdoc, I am more than happy to have contributors on any of my google projects. That is why I put them up there in the first place.

Cheers
R


On Wed, Oct 12, 2011 at 10:19 PM, David Peek <[hidden email]> wrote:
Michael,

I really love your library and use it on a daily basis when I need fast, documented and well tested utilities :) Thanks so much for sharing it!

Just noticed this in your docs:

x : Array<toArray3.T>


I wasn't aware of this syntax... is it a way to label your generics? Very useful :)

David

On 13/10/2011, at 2:02 AM, Michael Baczynski wrote:

I would suggest using chxdoc - it's a wonderful tool written in haXe, fully customizable and besides some minor quirks works great. I'm using it for documenting my library, see http://www.polygonal.de/doc/ds/

On 12.10.2011 15:45, Chman wrote:

Michael Cann wrote:

Personally I like how haXe is documented and prefer it over a javadoc
view.
Plus if there is something you dont fully understand from the docs
provided
you can always press F4 (from flash develop) and have a peek at the
source.


Well, Javadoc/Asdoc have the advantages of being organized. You can clearly
see what's a property, what's a method, what's inherited and what's not. For
example, take a look at the BitmapData documentation :

Haxe : http://haxe.org/api/flash9/display/bitmapdata
AS3 :
http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/display/BitmapData.html

The Asdoc version is really clean and easy to browse IMO. And I think the
community would benefit from having something like that for Haxe.


Michael Cann wrote:

As for your comments on the NME forum I agree that it could do with a
little
bit of polish but its perfectly serviceable and as its a free, open-source
project I think its difficult to complain, it does the job just fine for
now
IMO.


Oh, I'm not complaining, I love NME and I thank its authors for their hard
work ! I'm just saying that the forum engine used on Haxenme.org feels
hackish as well. Why do things differently when you can use something
powerful and scalable like SMF with a custom theme ? Once again, it's just
for the good of the community :)

- Tom

--
View this message in context: http://haxe.1354130.n2.nabble.com/Haxe-NME-Documentation-tp6884131p6885047.html
Sent from the Haxe mailing list archive at Nabble.com.



--
haXe - an open source web programming language
http://haxe.org


--
haXe - an open source web programming language
http://haxe.org


--
haXe - an open source web programming language
http://haxe.org
Reply | Threaded
Open this post in threaded view
|

Re: Haxe, NME, Documentation

Eric Priou


Le 13 oct. 2011 à 07:30, Russell Weir a écrit :

> I'm glad that at least one project is using chxdoc (great template btw), and it probably is quirky now, since it's hard to keep up with Nicolas' progress.
>
There is 2 actually ;)
http://community.silexlabs.org/cocktail/

---
Eric Priou aka erixtekila
http://www.ericpriou.net


--
haXe - an open source web programming language
http://haxe.org