Haxe Manual

[Caleb Harper]

Hi all,

I've been lurking for a while, and I decided it was time to try and contribute something.

I noticed the Haxe Manual hadn't been updated recently.  I imagine the the people working on the manual got busy improving the language and adding cool, new features.  

So I forked the manual and read through it.  I fixed any general typos I found.  I also added in comments / questions where I (as someone who didn't help write the compiler ;) ) got confused or thought more detail would be beneficial.  They show up as comment bubbles in the HaxeDoc.pdf or as TODO blocks in md/manual MarkDown files.  

I'm hoping the community will be able to help by:

1. Glancing through the manual and looking for typos / errors

2. Answer the questions I added to the document ( I will eventually work out the answers, but if you can jump start the process, please do! )

3. Filling in the missing sections of the manual  ( If you don't like LaTeX, or you feel like you've already written the section in a blog somewhere, just sent me the info and I'll be happy to integrate it)

4. Giving definitive answers to vocabulary issues (e.g. anonymous structs vs. anonymous objects, functions vs. methods, etc)

Thanks!

Caleb

P.S.  If anyone feels like I'm stepping on their toes, and they'd rather spearhead this effort, please just say so.

[Simon Krajewski]

> Pull a vocabulary page out of the definitions?

The markdown converter already does that, see
https://github.com/cahman/HaxeManual/blob/master/md/manual/dictionary.md

> Is “2.1 Basic Type” not a type group?

Basic types are abstracts with a @:coreType metadata. They are special
in that they do not have an underlying type. We do not have to list them
at separate type group, but we should mention @:coreType somewhere and
also explain how basic types are represented in the Basic Type section.

> Optional parameters is referred to as “optional Arguments” later in
> the manual. For con- sistency sake, do we prefer parameter or argument?

We should be using "argument" indeed because "parameter" usually refers
to type parameters.

> Later the manual uses “method” instead of “function.” I think they’re
> generally un- derstood to be inter- changeable, but for consistency, I
> think it should use one or the other throughout

I think I mention somewhere that I make the distinction between methods
as class fields and functions as methods + closures. However, this means
we should use "method" in this place.

> The comment on line 7 is confusing, maybe it should read “//Red is
> type enumValue not Enum¡Color¿”?

That's actually the error the compiler gives.

> What is a valid field- name?

That's explained in the Expressions section, we should reference it.

> I’m gussing it’s the non-static targets (JS, php) that make code like
> this?

I think all targets but Flash generate code like that.

> So what is the type of that array, or is it a compile error now?

It's a compilation error.

> Different from abstract classes in other lan- guages. Maybe we should
> mention that explicitly.

Yeah, this is sometimes confused by people. I think it would make a nice
trivia box.

> Change this to a flow chart?

Yes, we could do that later.

> Shoudl array access be part of the opera- tor overloading? Are
> brackets considered an operator?

No, brackets are not an operator in Haxe. They have their own syntax
(EArray) and typed AST (TArray) nodes.

> The formatting of the pdf is wrong here. Possibly due to how lessthan
> and greaterthen are set in the .tex file?

Possibly, that's the kind of stuff I'd deal with during final editing.

> I hope there is there a compiler warning about conflicts like this?

There's no special warning, but you will likely get an error if you try
to access haxe.Type with haxe being a local variable.

> A little different than the ’standard’ OOP definitions. A thing
> contained in an ob- ject is usually called a ’member.’ Might be worth
> pointing out the difference to other ’OOP’ languages.

Really? I always considered "member" to be the opposite of "static" in a
sense.

> I think it makes sense to talk about flags here (static, dynamic, over-
> ride, public, and pri- vate)

These have their own section a bit later.

> Confused by this. Are they saying the fields are of type dynamic, or
> the access identifier is dynamic?

That's actually just a typo, it is supposed to say "assign a class with
properties TO Dynamic".

> I don’t understand. If it isn’t a ’physi- cal field’ then what is it?
> Why would you ever want a field that wasn’t a physical field?

If a field has both a getter and a setter it's entirely possible that
there is no "storage" required for it. For instance, you could have a
linked list data structure with a field length(get, never):Int, where
get_length would calculate the value by counting the elements (yes,
that's not good design).

> Is vocabulary con- sistent: visibility vs. accessibility? If so,
> what’s the difference?

You can have a field which is visible to you, but still cannot be
accessed in a specific way. I guess we don't have to talk about
"accessibility" though.

> which targets suffer the most from function calls? Guessing flash?
> So how do we tell if a function performs better inline? Use a code
> profiler?

Yeah, that and general experience. It's hard to give any real advice
here because it depends on many circumstances. For instance, even very
short functions can be bad inlining candidates if they use an argument
multiple times.

> What about overriding variables? Something I can easily check when I
> have the time..

Not allowed in Haxe. We should mention it though.

> I feel like a quick intro to expressions should come sooner in the manual.

Maybe, but I don't like splitting content like that. The manual
currently has a nice top-down flow from types over fields to expressions.

> Anonymous Objects are synonymous with Anonymous Struc- tures? Objects
> are the same as structures? Want to be sure to use consistent vocab

Good point, we shouldn't be talking about "object" there because that
term is heavily overloaded. It might be better to talk about structures.

> Talk about the try catch keyword here, but I feel like excep- tions
> should have their own, larger’ish section.

I thought about that, but I wouldn't really know what to tell about them
beyond their syntax.

> Is this section going to overlap with the API documentation. Would it
> make sense to just pull in that informa- tion?

This section is supposed to introduce specific parts of the standard
library: What are they used for? How are they used?

> There are more static extensions, like Date- Tools. Should this list
> all of the static exten- sions, or just some exapmles?

DateTools was not designed as static extension class, it just happens to
have that Tools suffix. We can mention all static extension classes of
the standard library, but I think I already do that.

> There should probably be a whole section on Iterables?

Agreed, that can go to the features section.

> Just a stlye question: When to use Fullref vs tref?

Ah, we have to make that consistent. I hadn't used LateX for years when
I started with the manual and was struggling a bit to get references right.

> I think \ would be more inuitive as an escape sequence than $ Just
> curious about the design decision.

That's how C printf escapes % as well.

In general: A huge THANKS for your comments and work on this. It's the
first real contribution I've had beyond typo fixes and I really
appreciate it. Let me know if you have further questions!

Simon

[LE JOLLY David]

Hi !

Where can I read your forked manual ?

thanks.

2013/11/7 Caleb Harper <harp...@gmail.com>

--
To post to this group haxe...@googlegroups.com
http://groups.google.com/group/haxelang?hl=en
---
You received this message because you are subscribed to the Google Groups "Haxe" group.
For more options, visit https://groups.google.com/groups/opt_out.

--
Le Jolly David
Résidence Montesquieu porte 6

5Bis rue Montesquieu
49000 ANGERS

06 67 56 57 93

09 53 85 50 79

[Nicolas Cannasse]

Le 07/11/2013 21:05, Caleb Harper a �crit :

Thanks, any help in that area is greatly appreciated. That makes me
think that we should use Pull Requests to handle Manual community
contributions, and have the (soon ready) new haxe.org website update its
content from GitHub on a regular basis.

@Jason: sounds good ?

Best,
Nicolas

[Jason O'Neil]

Hi Nicolas

I'm going to use a post-commit trigger on Github to trigger an update on the website.  Whether the canonical version that people can contribute to is the Markdown or the Latex I don't mind.  Simn is the main writer so it's fair for him to use what he wanted, but it may be easier to get contributions with Markdown? 

Either way I don't mind.  I can make the post-commit trigger compile the markdown from the latex if needed ;)

Jason

On Fri, Nov 8, 2013 at 4:51 PM, Nicolas Cannasse <ncan...@gmail.com> wrote:

[Jason O'Neil]

Well done to both Simon and Caleb on the manual by the way...  It's looking like a really solid resource.  I am appreciative!

[Luca]

The problem with taking contributions in markdown would surely be that those changes would have to be back-ported to the latex source? 

[Simon Krajewski]

Am 08.11.2013 09:55, schrieb Jason O'Neil:
> Hi Nicolas
>
> I'm going to use a post-commit trigger on Github to trigger an update
> on the website. Whether the canonical version that people can
> contribute to is the Markdown or the Latex I don't mind. Simn is the
> main writer so it's fair for him to use what he wanted, but it may be
> easier to get contributions with Markdown?
>
> Either way I don't mind. I can make the post-commit trigger compile
> the markdown from the latex if needed ;)

I insist on the .tex being the main source for various reasons. I also
find it hard to believe that someone with the skills and time to write
quality content would be prevented from contributing by LateX of all things.

Simon

[Jason O'Neil]

That's fine - when I get to it I'll ask your help doing an automatic compile of the tex->markdown so that we can automatically merge changes.

I've never had to write in LateX but it seems like you could figure it out easily enough by copying what is done throughout the document so I don't mind.

[Simon Krajewski]

Am 08.11.2013 10:20, schrieb Jason O'Neil:
> That's fine - when I get to it I'll ask your help doing an automatic
> compile of the tex->markdown so that we can automatically merge changes.

Caleb documented that as well (thanks!):
https://github.com/cahman/HaxeManual/tree/master/convert

Simon

[Jason O'Neil]

I forgot that you used hxparse for this :D

Simon

[Caleb Harper]

Oh my!  Can't believe I forgot to post the link... But hopefully the changes will be merged in with Simon's repository before long.

On an aside, it would be great if a webdev could fill in the Haxe Manual section on Remoting (currently Section 7.11).  If LaTeX is a barrier to entry, feel free to send me something in your favorite format (word doc, txt file, Morse code, etc.), and I'll happily convert and integrate it into the manual.

Cheers,

Caleb