About online API

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

About online API

Nicolas Cannasse
Hi,

There's been some misunderstandings about the way the online API on
http://haxe.org/api is working, so I'll try to sum it up here.

For every new haXe version, the API is extracted from original haXe
sources by using the compiler -xml output. This includes the
documentation when it exists in the sources.

Then we are running a program that will connect to the Wiki and
"synchronize" the API.

It means it will remove the no longer available methods and fields, and
add the new classes, packages, methods and fields.

During this process, if some documentation is available on the Wiki, it
will keep it as-it, so online documentation edited by users is NEVER
lost as soon as it's appropriately placed inside the [doc][/doc] tags.

This was made that way to allow users to freely complete+translate the
online documentation as they wish. So please feel free to do so.

Best,
Nicolas

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

Re: About online API

Wojtek Danilo
I'm reading for a couple of days about not-complete haxe documentation. And I've got a question now to all people, who are feeling that Haxe is great language and need good documentation. Maybe each person, who is able to complete part of documentation will do it in such a way:
If you're working with flash or neko or ... AND you want to help with completing the api then reply to this mail writing
"platform : nick". And every week each person from this list will "become" a small part from the api to complete.
I thing that is the fastest way, because I don't think that one person will be able to complete this documentation fast and good.

If you don't like this idea, no problem :P That is only proposition :)

Wojtek Daniło


2009/4/15 Nicolas Cannasse <[hidden email]>
Hi,

There's been some misunderstandings about the way the online API on http://haxe.org/api is working, so I'll try to sum it up here.

For every new haXe version, the API is extracted from original haXe sources by using the compiler -xml output. This includes the documentation when it exists in the sources.

Then we are running a program that will connect to the Wiki and "synchronize" the API.

It means it will remove the no longer available methods and fields, and add the new classes, packages, methods and fields.

During this process, if some documentation is available on the Wiki, it will keep it as-it, so online documentation edited by users is NEVER lost as soon as it's appropriately placed inside the [doc][/doc] tags.

This was made that way to allow users to freely complete+translate the online documentation as they wish. So please feel free to do so.

Best,
Nicolas

--
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: About online API

Benjamin Dasnois
Hello,

I think now is the time to get a comprehensive documentation. The
documentation, as it is right now, is split in two main parts :

   - Languages References, tutorials,.... those are great and the
localization was a great idea but unfortunately, I guess most pages
are now out of sync (remember the download-the-last-version problem
Nicolas ?)
   - The API

I'm trying to keep and as much as possible the French pages in sync
with the English ones when I'm editing one, but this is obviously NOT
the case for every language. Why ? Because we don't have a person
responsible for each language (kind of coordinator) and because we
don't have the appropriate tools that would show for example "This
page has been edited in English since you last reviewed it in your own
language" (and a tool like this could be brought to something more
advanced too).

Also Nicolas, sometimes we have discussion on this list that lead to a
new information regarding the language, and I tend to modify the
language ref to mirror these informations, most of the time I modify
both French and English ones (I think last time was optionnal
arguments and compile-time) but it is clearly difficult for other
language maintainer (if any) to follow-up ! In fact, looking at the
change history, no one has mirrored those changes.


So if you agree Nicolas, I would like to start a documentation
project, with one "lead maintainer" for each language.

This method can also be applied to the API.

Regards,

2009/4/15 Haxe <[hidden email]>:

> I'm reading for a couple of days about not-complete haxe documentation. And
> I've got a question now to all people, who are feeling that Haxe is great
> language and need good documentation. Maybe each person, who is able to
> complete part of documentation will do it in such a way:
> If you're working with flash or neko or ... AND you want to help with
> completing the api then reply to this mail writing
> "platform : nick". And every week each person from this list will "become" a
> small part from the api to complete.
> I thing that is the fastest way, because I don't think that one person will
> be able to complete this documentation fast and good.
>
> If you don't like this idea, no problem :P That is only proposition :)
>
> Wojtek Daniło
>
>
> 2009/4/15 Nicolas Cannasse <[hidden email]>
>>
>> Hi,
>>
>> There's been some misunderstandings about the way the online API on
>> http://haxe.org/api is working, so I'll try to sum it up here.
>>
>> For every new haXe version, the API is extracted from original haXe
>> sources by using the compiler -xml output. This includes the documentation
>> when it exists in the sources.
>>
>> Then we are running a program that will connect to the Wiki and
>> "synchronize" the API.
>>
>> It means it will remove the no longer available methods and fields, and
>> add the new classes, packages, methods and fields.
>>
>> During this process, if some documentation is available on the Wiki, it
>> will keep it as-it, so online documentation edited by users is NEVER lost as
>> soon as it's appropriately placed inside the [doc][/doc] tags.
>>
>> This was made that way to allow users to freely complete+translate the
>> online documentation as they wish. So please feel free to do so.
>>
>> Best,
>> Nicolas
>>
>> --
>> haXe - an open source web programming language
>> http://haxe.org
>
>
> --
> haXe - an open source web programming language
> http://haxe.org
>



--
DASNOIS Benjamin
http://www.benjamindasnois.com

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

Re: About online API

Ron Wheeler
Benjamin Dasnois wrote:

> Hello,
>
> I think now is the time to get a comprehensive documentation. The
> documentation, as it is right now, is split in two main parts :
>
>    - Languages References, tutorials,.... those are great and the
> localization was a great idea but unfortunately, I guess most pages
> are now out of sync (remember the download-the-last-version problem
> Nicolas ?)
>    - The API
>
> I'm trying to keep and as much as possible the French pages in sync
> with the English ones when I'm editing one, but this is obviously NOT
> the case for every language. Why ? Because we don't have a person
> responsible for each language (kind of coordinator) and because we
> don't have the appropriate tools that would show for example "This
> page has been edited in English since you last reviewed it in your own
> language" (and a tool like this could be brought to something more
> advanced too).
>
> Also Nicolas, sometimes we have discussion on this list that lead to a
> new information regarding the language, and I tend to modify the
> language ref to mirror these informations, most of the time I modify
> both French and English ones (I think last time was optionnal
> arguments and compile-time) but it is clearly difficult for other
> language maintainer (if any) to follow-up ! In fact, looking at the
> change history, no one has mirrored those changes.
>
>
> So if you agree Nicolas, I would like to start a documentation
> project, with one "lead maintainer" for each language.
>
> This method can also be applied to the API.
>
> Regards,
>
> 2009/4/15 Haxe <[hidden email]>:
>  
>> I'm reading for a couple of days about not-complete haxe documentation. And
>> I've got a question now to all people, who are feeling that Haxe is great
>> language and need good documentation. Maybe each person, who is able to
>> complete part of documentation will do it in such a way:
>> If you're working with flash or neko or ... AND you want to help with
>> completing the api then reply to this mail writing
>> "platform : nick". And every week each person from this list will "become" a
>> small part from the api to complete.
>> I thing that is the fastest way, because I don't think that one person will
>> be able to complete this documentation fast and good.
>>
>> If you don't like this idea, no problem :P That is only proposition :)
>>
>> Wojtek Daniło
>>
>>
>> 2009/4/15 Nicolas Cannasse <[hidden email]>
>>    
>>> Hi,
>>>
>>> There's been some misunderstandings about the way the online API on
>>> http://haxe.org/api is working, so I'll try to sum it up here.
>>>
>>> For every new haXe version, the API is extracted from original haXe
>>> sources by using the compiler -xml output. This includes the documentation
>>> when it exists in the sources.
>>>
>>> Then we are running a program that will connect to the Wiki and
>>> "synchronize" the API.
>>>
>>> It means it will remove the no longer available methods and fields, and
>>> add the new classes, packages, methods and fields.
>>>
>>> During this process, if some documentation is available on the Wiki, it
>>> will keep it as-it, so online documentation edited by users is NEVER lost as
>>> soon as it's appropriately placed inside the [doc][/doc] tags.
>>>
>>> This was made that way to allow users to freely complete+translate the
>>> online documentation as they wish. So please feel free to do so.
>>>
>>> Best,
>>> Nicolas
>>>
>>> --
>>> haXe - an open source web programming language
>>> http://haxe.org
>>>      
>> --
>> haXe - an open source web programming language
>> http://haxe.org
>>
>>    
>
>
>
>  
I agree that it is time to do something about the documentation.

The key thing is to get the API documentation that is produced from the
code, to a better state.
This is always the most accurate starting point for other work since it
should reflect the actual functioning software.
It does depend on people making changes to the API to actually update
the documentation in the code but I have more faith in that happening,
than I do in users noticing that something has changed and figuring out
what the impact is on the wiki description.

 From a reasonable set of API documentation, we can create additional
tutorials and notes.

The notes should be at the package level since class notes should be in
the code.

What is the best way to get the code up-to-date?
Can we live with a unilingual API reference produced from the code?
English or French?
My own personal preference would be for an English API reference but I
could live with French.
I would be willing to be a reviewer of the API documentation. I could
not edit the French version.

We need a checklist of code that is "acceptable" and a list of code that
is "ready for review" and a list of classes that are urgently in need of
work by a programmer who can read the code and write the initial
documentation.

Package level notes can be done on the wiki.
Do we want to maintain a list of which notes are originated in which
language and are ready for translation to other languages.

On the tutorial side, we could produce a list of tutorials that are
"finished".
By finished, I mean written and reviewed in its native language and
ready for translation into other languages.

This implies that each tutorial has a native language from which other
translations are derived.
This also implies a team of reviewers for each language in which
original material is produced.


Once one gets into a multi-language situation, document control becomes
important so that authoring and translation stay in synch and users can
find out what docs are up-to-date if they can read multiple languages.


Does this make sense?

Ron



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

Re: About online API

back2dos
Ron Wheeler wrote:

> Benjamin Dasnois wrote:
>> Hello,
>>
>> I think now is the time to get a comprehensive documentation. The
>> documentation, as it is right now, is split in two main parts :
>>
>>    - Languages References, tutorials,.... those are great and the
>> localization was a great idea but unfortunately, I guess most pages
>> are now out of sync (remember the download-the-last-version problem
>> Nicolas ?)
>>    - The API
>>
>> I'm trying to keep and as much as possible the French pages in sync
>> with the English ones when I'm editing one, but this is obviously NOT
>> the case for every language. Why ? Because we don't have a person
>> responsible for each language (kind of coordinator) and because we
>> don't have the appropriate tools that would show for example "This
>> page has been edited in English since you last reviewed it in your own
>> language" (and a tool like this could be brought to something more
>> advanced too).
>>
>> Also Nicolas, sometimes we have discussion on this list that lead to a
>> new information regarding the language, and I tend to modify the
>> language ref to mirror these informations, most of the time I modify
>> both French and English ones (I think last time was optionnal
>> arguments and compile-time) but it is clearly difficult for other
>> language maintainer (if any) to follow-up ! In fact, looking at the
>> change history, no one has mirrored those changes.
>>
>>
>> So if you agree Nicolas, I would like to start a documentation
>> project, with one "lead maintainer" for each language.
>>
>> This method can also be applied to the API.
>>
>> Regards,
>>
>> 2009/4/15 Haxe <[hidden email]>:
>>  
>>> I'm reading for a couple of days about not-complete haxe
>>> documentation. And
>>> I've got a question now to all people, who are feeling that Haxe is
>>> great
>>> language and need good documentation. Maybe each person, who is able to
>>> complete part of documentation will do it in such a way:
>>> If you're working with flash or neko or ... AND you want to help with
>>> completing the api then reply to this mail writing
>>> "platform : nick". And every week each person from this list will
>>> "become" a
>>> small part from the api to complete.
>>> I thing that is the fastest way, because I don't think that one
>>> person will
>>> be able to complete this documentation fast and good.
>>>
>>> If you don't like this idea, no problem :P That is only proposition :)
>>>
>>> Wojtek Daniło
>>>
>>>
>>> 2009/4/15 Nicolas Cannasse <[hidden email]>
>>>    
>>>> Hi,
>>>>
>>>> There's been some misunderstandings about the way the online API on
>>>> http://haxe.org/api is working, so I'll try to sum it up here.
>>>>
>>>> For every new haXe version, the API is extracted from original haXe
>>>> sources by using the compiler -xml output. This includes the
>>>> documentation
>>>> when it exists in the sources.
>>>>
>>>> Then we are running a program that will connect to the Wiki and
>>>> "synchronize" the API.
>>>>
>>>> It means it will remove the no longer available methods and fields,
>>>> and
>>>> add the new classes, packages, methods and fields.
>>>>
>>>> During this process, if some documentation is available on the
>>>> Wiki, it
>>>> will keep it as-it, so online documentation edited by users is
>>>> NEVER lost as
>>>> soon as it's appropriately placed inside the [doc][/doc] tags.
>>>>
>>>> This was made that way to allow users to freely complete+translate the
>>>> online documentation as they wish. So please feel free to do so.
>>>>
>>>> Best,
>>>> Nicolas
>>>>
>>>> --
>>>> haXe - an open source web programming language
>>>> http://haxe.org
>>>>      
>>> --
>>> haXe - an open source web programming language
>>> http://haxe.org
>>>
>>>    
>>
>>
>>
>>  
> I agree that it is time to do something about the documentation.
>
> The key thing is to get the API documentation that is produced from
> the code, to a better state.
> This is always the most accurate starting point for other work since
> it should reflect the actual functioning software.
> It does depend on people making changes to the API to actually update
> the documentation in the code but I have more faith in that happening,
> than I do in users noticing that something has changed and figuring
> out what the impact is on the wiki description.
>
> From a reasonable set of API documentation, we can create additional
> tutorials and notes.
>
> The notes should be at the package level since class notes should be
> in the code.
>
> What is the best way to get the code up-to-date?
> Can we live with a unilingual API reference produced from the code?
> English or French?
> My own personal preference would be for an English API reference but I
> could live with French.
> I would be willing to be a reviewer of the API documentation. I could
> not edit the French version.
>
> We need a checklist of code that is "acceptable" and a list of code
> that is "ready for review" and a list of classes that are urgently in
> need of work by a programmer who can read the code and write the
> initial documentation.
>
> Package level notes can be done on the wiki.
> Do we want to maintain a list of which notes are originated in which
> language and are ready for translation to other languages.
>
> On the tutorial side, we could produce a list of tutorials that are
> "finished".
> By finished, I mean written and reviewed in its native language and
> ready for translation into other languages.
>
> This implies that each tutorial has a native language from which other
> translations are derived.
> This also implies a team of reviewers for each language in which
> original material is produced.
>
>
> Once one gets into a multi-language situation, document control
> becomes important so that authoring and translation stay in synch and
> users can find out what docs are up-to-date if they can read multiple
> languages.
>
>
> Does this make sense?
>
> Ron
>
>
>
hiho,

first of all, i think at class level, documentation should come out of
the source, as it does ... the question is, how would it possible, that
willing documentators could change it ...
and personally, i really don't think it has to be multilingual ...
sticking with english should really suffice ... once it is moreless
complete, and doublechecked, we can think about multilanguage again ...
i think, it'd be quite hard to maintain (you'd have to find someone who
a) has the enthusiasm and b) sufficient skills in two languages to
translate everything and c) would always find someone else who'd
translate updates to their language), even if kept in a single file,
which is what'd work best i think ... maybe something like this (i don't
quite know the syntax used by haXe right now, but i think you'll all
understand :-D ):

/**
* <en>method for frying frogs
* @param frogs frogs to be grilled
* @param temperature temperature to be used</en>
* <fr>methode pour griller des grenouilles
* @param frogs les grenouilles a griller
* @param temperature la temperature a utiliser</fr>
* ...
*/
public function
grillFrogs(frogs:Iterable<Grenouille>,temperature:Int):Void {
    //... the magic ...
}

and users working on the api could then download haXe with multilingual
documentation, and there would be one uniligual version of haXe per
language, too, for "simple" users ...
and if something is not defined for a specific language, it should
default to english in the unilingual version ... but yeah, as i said,
english should do the trick i guess ... livedocs are also only available
in english (or i'm to stupid to find them) ...

i totally agree, some package level documentation would also be really
cool ... unlike the AS3 documentation, it could really explain a bit,
how things work together and point out main classes, best practices,
code snippets etc. ... i think it wouldn't be bad, if they were actually
kept with the source ... just some files (tex, html or whatever)
floating around ... so you'd always have things on your machine ... and
when installing haXe, it'd generate you a local reference from the
files, if you want to ...
actual tutorials should be kept apart and maintained in the wiki
directly of course ...

i'd be willing to work on the flash and flash9 documentation ...
although livedocs is not bad (well sometimes it's painfully slow), it'd
be great to have it right in the code (for editors offering tooltips)
and also you don't need to look in 2 references ...

just my 1.5 cents ... ;)

greetz
back2dos

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

Re: About online API

Tony Polinelli
would adding all of this extra bulk to the stadard class files (full documentation in multi languages) have an effect on the speed of the compiler? i know that it *should* be minimal- but still

Tony Polinelli
http://www.touchmypixel.com


2009/4/16 Juraj Kirchheim <[hidden email]>
Ron Wheeler wrote:
Benjamin Dasnois wrote:
Hello,

I think now is the time to get a comprehensive documentation. The
documentation, as it is right now, is split in two main parts :

  - Languages References, tutorials,.... those are great and the
localization was a great idea but unfortunately, I guess most pages
are now out of sync (remember the download-the-last-version problem
Nicolas ?)
  - The API

I'm trying to keep and as much as possible the French pages in sync
with the English ones when I'm editing one, but this is obviously NOT
the case for every language. Why ? Because we don't have a person
responsible for each language (kind of coordinator) and because we
don't have the appropriate tools that would show for example "This
page has been edited in English since you last reviewed it in your own
language" (and a tool like this could be brought to something more
advanced too).

Also Nicolas, sometimes we have discussion on this list that lead to a
new information regarding the language, and I tend to modify the
language ref to mirror these informations, most of the time I modify
both French and English ones (I think last time was optionnal
arguments and compile-time) but it is clearly difficult for other
language maintainer (if any) to follow-up ! In fact, looking at the
change history, no one has mirrored those changes.


So if you agree Nicolas, I would like to start a documentation
project, with one "lead maintainer" for each language.

This method can also be applied to the API.

Regards,

2009/4/15 Haxe <[hidden email]>:
 
I'm reading for a couple of days about not-complete haxe documentation. And
I've got a question now to all people, who are feeling that Haxe is great
language and need good documentation. Maybe each person, who is able to
complete part of documentation will do it in such a way:
If you're working with flash or neko or ... AND you want to help with
completing the api then reply to this mail writing
"platform : nick". And every week each person from this list will "become" a
small part from the api to complete.
I thing that is the fastest way, because I don't think that one person will
be able to complete this documentation fast and good.

If you don't like this idea, no problem :P That is only proposition :)

Wojtek Daniło


2009/4/15 Nicolas Cannasse <[hidden email]>
 
Hi,

There's been some misunderstandings about the way the online API on
http://haxe.org/api is working, so I'll try to sum it up here.

For every new haXe version, the API is extracted from original haXe
sources by using the compiler -xml output. This includes the documentation
when it exists in the sources.

Then we are running a program that will connect to the Wiki and
"synchronize" the API.

It means it will remove the no longer available methods and fields, and
add the new classes, packages, methods and fields.

During this process, if some documentation is available on the Wiki, it
will keep it as-it, so online documentation edited by users is NEVER lost as
soon as it's appropriately placed inside the [doc][/doc] tags.

This was made that way to allow users to freely complete+translate the
online documentation as they wish. So please feel free to do so.

Best,
Nicolas

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

   



 
I agree that it is time to do something about the documentation.

The key thing is to get the API documentation that is produced from the code, to a better state.
This is always the most accurate starting point for other work since it should reflect the actual functioning software.
It does depend on people making changes to the API to actually update the documentation in the code but I have more faith in that happening, than I do in users noticing that something has changed and figuring out what the impact is on the wiki description.

>From a reasonable set of API documentation, we can create additional tutorials and notes.

The notes should be at the package level since class notes should be in the code.

What is the best way to get the code up-to-date?
Can we live with a unilingual API reference produced from the code? English or French?
My own personal preference would be for an English API reference but I could live with French.
I would be willing to be a reviewer of the API documentation. I could not edit the French version.

We need a checklist of code that is "acceptable" and a list of code that is "ready for review" and a list of classes that are urgently in need of work by a programmer who can read the code and write the initial documentation.

Package level notes can be done on the wiki.
Do we want to maintain a list of which notes are originated in which language and are ready for translation to other languages.

On the tutorial side, we could produce a list of tutorials that are "finished".
By finished, I mean written and reviewed in its native language and ready for translation into other languages.

This implies that each tutorial has a native language from which other translations are derived.
This also implies a team of reviewers for each language in which original material is produced.


Once one gets into a multi-language situation, document control becomes important so that authoring and translation stay in synch and users can find out what docs are up-to-date if they can read multiple languages.


Does this make sense?

Ron



hiho,

first of all, i think at class level, documentation should come out of the source, as it does ... the question is, how would it possible, that willing documentators could change it ...
and personally, i really don't think it has to be multilingual ... sticking with english should really suffice ... once it is moreless complete, and doublechecked, we can think about multilanguage again ...
i think, it'd be quite hard to maintain (you'd have to find someone who a) has the enthusiasm and b) sufficient skills in two languages to translate everything and c) would always find someone else who'd translate updates to their language), even if kept in a single file, which is what'd work best i think ... maybe something like this (i don't quite know the syntax used by haXe right now, but i think you'll all understand :-D ):

/**
* <en>method for frying frogs
* @param frogs frogs to be grilled
* @param temperature temperature to be used</en>
* <fr>methode pour griller des grenouilles
* @param frogs les grenouilles a griller
* @param temperature la temperature a utiliser</fr>
* ...
*/
public function grillFrogs(frogs:Iterable<Grenouille>,temperature:Int):Void {
  //... the magic ...
}

and users working on the api could then download haXe with multilingual documentation, and there would be one uniligual version of haXe per language, too, for "simple" users ...
and if something is not defined for a specific language, it should default to english in the unilingual version ... but yeah, as i said, english should do the trick i guess ... livedocs are also only available in english (or i'm to stupid to find them) ...

i totally agree, some package level documentation would also be really cool ... unlike the AS3 documentation, it could really explain a bit, how things work together and point out main classes, best practices, code snippets etc. ... i think it wouldn't be bad, if they were actually kept with the source ... just some files (tex, html or whatever) floating around ... so you'd always have things on your machine ... and when installing haXe, it'd generate you a local reference from the files, if you want to ...
actual tutorials should be kept apart and maintained in the wiki directly of course ...

i'd be willing to work on the flash and flash9 documentation ... although livedocs is not bad (well sometimes it's painfully slow), it'd be great to have it right in the code (for editors offering tooltips) and also you don't need to look in 2 references ...

just my 1.5 cents ... ;)

greetz
back2dos

--
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: About online API

Zjnue Brzavi
> would adding all of this extra bulk to the stadard class files (full
> documentation in multi languages) have an effect on the speed of the
> compiler? i know that it *should* be minimal- but still

Personally I would dread the sight of hefty comments in the code. It
is a delight to read NC's elegant and bloat-free code. A few guiding
comments may well help here and there, but my preference would be to
have them few and far between.

I think in order to cater for different preferences, it may help to
inject comments from other places (like the Wiki) instead, providing
parameters for preferred language(s), bulk level, etc..

Zjnue

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

Re: About online API

David Bergman
In reply to this post by Nicolas Cannasse
On Apr 15, 2009, at 3:23 AM, Nicolas Cannasse wrote:

> Hi,
>
> There's been some misunderstandings about the way the online API on http://haxe.org/api 
>  is working, so I'll try to sum it up here.
>
> For every new haXe version, the API is extracted from original haXe  
> sources by using the compiler -xml output. This includes the  
> documentation when it exists in the sources.
>
> Then we are running a program that will connect to the Wiki and  
> "synchronize" the API.
>
> It means it will remove the no longer available methods and fields,  
> and add the new classes, packages, methods and fields.
>
> During this process, if some documentation is available on the Wiki,  
> it will keep it as-it, so online documentation edited by users is  
> NEVER lost as soon as it's appropriately placed inside the [doc][/
> doc] tags.
>
> This was made that way to allow users to freely complete+translate  
> the online documentation as they wish. So please feel free to do so.

I think there should be an API section of the site which is not  
editable, but *only* synchronized with (the haxedoc comments of) the  
code.

I can definitely help out to go through all code and make haxedoc  
comments. The question is what to do after I have this patched source  
code, and what version I should use as the base one for my diffs.

In my overly humble opinion, translations is a second-order problem,  
only of interest when we have a core API documentation we all feel  
comfortable with; which should have at least a few words per method.

/David

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

Re: About online API

David Bergman
In reply to this post by Benjamin Dasnois
On Apr 15, 2009, at 5:17 AM, Benjamin Dasnois wrote:

> So if you agree Nicolas, I would like to start a documentation
> project, with one "lead maintainer" for each language.
>
> This method can also be applied to the API.

Well, we should not use the Wiki pages to comment the API; at least  
not before having provided adequate haxedoc comments in code.

Again, my humble opinion.

/David

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

Re: About online API

David Bergman
In reply to this post by Zjnue Brzavi
On Apr 15, 2009, at 1:40 PM, Zjnue Brzavi wrote:

>> would adding all of this extra bulk to the stadard class files (full
>> documentation in multi languages) have an effect on the speed of the
>> compiler? i know that it *should* be minimal- but still
>
> Personally I would dread the sight of hefty comments in the code. It
> is a delight to read NC's elegant and bloat-free code. A few guiding
> comments may well help here and there, but my preference would be to
> have them few and far between.

We are talking about the haxedoc comments and, specifically, about the  
generated API documentation you get from such comments. Yes, I agree  
with you that too many naive comments in code is silly for those  
reading/maintaining code. But one should be able to understand what an  
API is doing without resorting to reading the code. So, we do need  
those haxedoc comments.

In most Java projects, I try to have my team understand the  
distinction between pure code comments, helping out with the  
understanding of the code for maintainers (and wannabes :-) ), on one  
hand and the Javadoc/doxygen commnents, on the other hand, where the  
audience are the *users* of those classes/functions.

> I think in order to cater for different preferences, it may help to
> inject comments from other places (like the Wiki) instead, providing
> parameters for preferred language(s), bulk level, etc..

Well, we do have this tool haxedoc, and documentation in code  
(comments...) has a much greater chance of being accurate than  
externally edited documentation.

We are not doing haxedoc a favor, market-wise, by only using it for  
some 50% of our own methods :-)

/David

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

Re: About online API

Ian Martins
In reply to this post by David Bergman
David Bergman wrote:
> On Apr 15, 2009, at 5:17 AM, Benjamin Dasnois wrote:
>
>> So if you agree Nicolas, I would like to start a documentation
>> project, with one "lead maintainer" for each language.
>>
>> This method can also be applied to the API.
>
> Well, we should not use the Wiki pages to comment the API; at least
> not before having provided adequate haxedoc comments in code.
this is really only a problem for people that generate their own
haxedoc's (like me).  the current situation should be fine for those
that only use the wiki api.

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

Re: About online API

David Bergman
On Apr 15, 2009, at 2:16 PM, Ian Martins wrote:

> David Bergman wrote:
>> On Apr 15, 2009, at 5:17 AM, Benjamin Dasnois wrote:
>>
>>> So if you agree Nicolas, I would like to start a documentation
>>> project, with one "lead maintainer" for each language.
>>>
>>> This method can also be applied to the API.
>>
>> Well, we should not use the Wiki pages to comment the API; at least  
>> not before having provided adequate haxedoc comments in code.
> this is really only a problem for people that generate their own  
> haxedoc's (like me).  the current situation should be fine for those  
> that only use the wiki api.

To have to maintain two sets of comments for the API methods and  
classes; is that not a problem even for those not wanting to generate ?

Even with Nicolas' method, to not override the comments of edited Wiki  
when synchronizing with the (extracted) haxedoc comments, this means  
we either (i) skip using haxedoc and slowly see more and (presumably  
even) better comments on the Wiki page or (ii) maintain two loci of  
comments, manually or semi-manually.

I kind of hoped we all could agree that the short comment-like  
documentation for the API should be in haxedoc format in code.

So, most people are fine with the "official" API being haxedoc with  
whatever edited on Wiki overriding any comment for that class/method/
whatever, thereby making the (merged, through Nicolas' method) Wiki  
page the official site of API documentation, with the in-code comments  
constituting a (not even proper sub set) part of it?

/David



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

Re: About online API

Nicolas Cannasse
In reply to this post by David Bergman
David Bergman a écrit :
>> This was made that way to allow users to freely complete+translate the
>> online documentation as they wish. So please feel free to do so.
>
> I think there should be an API section of the site which is not
> editable, but *only* synchronized with (the haxedoc comments of) the code.

Instead of trying to figure out how people can submit patches for the
API, and having myself work at integrating these, I prefer to let
everybody complete the Wiki API, fix the typos, etc

Then if at some time there is a need for it, we can still copy back the
Wiki API documentation into the sources by using a simple automated process.

Nicolas

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

Re: About online API

David Bergman
In reply to this post by Ian Martins
On Apr 15, 2009, at 2:16 PM, Ian Martins wrote:

> David Bergman wrote:
>> On Apr 15, 2009, at 5:17 AM, Benjamin Dasnois wrote:
>>
>>> So if you agree Nicolas, I would like to start a documentation
>>> project, with one "lead maintainer" for each language.
>>>
>>> This method can also be applied to the API.
>>
>> Well, we should not use the Wiki pages to comment the API; at least  
>> not before having provided adequate haxedoc comments in code.
> this is really only a problem for people that generate their own  
> haxedoc's (like me).  the current situation should be fine for those  
> that only use the wiki api.

[DISCLAIMER: if the tone of this - and others - post of mine sounds a  
bit whining, it is just because I want to make this great product even  
more attractive for developers, AND I am prepared to comment every  
single method of the haXe standard library, up to my at-a-glance  
understanding of it, in the next few days, in haxedoc]

To have to maintain two sets of comments for the API methods and  
classes; is that not a problem even for those not wanting to generate  
offline copies of the documentation?

Even with Nicolas' method, to not override the comments of edited Wiki  
when synchronizing with the (extracted) haxedoc comments, this means  
we either (i) skip using haxedoc and slowly see more and (presumably  
even) better comments on the Wiki page or (ii) maintain two loci of  
comments, manually or semi-manually. Note that as soon as a method's  
documentation is changed on the wiki, the haxedoc comments are  
suppressed, which will lead to people not commenting in-code in the  
end, since the Wiki editor(s) have the last word.

I kind of hoped we all could agree that the short comment-like  
documentation for the API should be in haxedoc format in code.

So, most people are fine with the "official" API being haxedoc with  
whatever edited on Wiki overriding any comment for that class/method/
whatever, thereby making the (merged, through Nicolas' method) Wiki  
page the official site of API documentation, with the in-code comments  
constituting just a (not even proper sub set) part of it?

/David



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

Re: About online API

David Bergman
In reply to this post by Nicolas Cannasse
On Apr 15, 2009, at 5:41 PM, Nicolas Cannasse wrote:

> David Bergman a écrit :
>>> This was made that way to allow users to freely complete+translate  
>>> the online documentation as they wish. So please feel free to do so.
>> I think there should be an API section of the site which is not  
>> editable, but *only* synchronized with (the haxedoc comments of)  
>> the code.
>
> Instead of trying to figure out how people can submit patches for  
> the API, and having myself work at integrating these, I prefer to  
> let everybody complete the Wiki API, fix the typos, etc

I would probably more work on getting the uncommented methods  
documented.

>
> Then if at some time there is a need for it, we can still copy back  
> the Wiki API documentation into the sources by using a simple  
> automated process.

I could definitely use the Wiki for these comments, if the  
understanding is that we indeed reverse engineer them back into the  
code, as haxedoc comments. If the idea is to keep these two  
repositories of API documentation, I just want to make sure I am on  
the Right Side of the equation, i.e., on the side which will override  
the other :-)

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

Re: About online API

Ron Wheeler
In reply to this post by David Bergman
I am not an expert on haxedoc. That being said, I will wade in anyway.

1) I hope that it can determine the difference between ordinary comments
and documentation.
2) API documentation should not occur intermixed with code. It should be
in a block at the class level and in a block for each method, above the
method. This should not interfere with those reading the code for sheer
enjoyment but will be close enough to the code to stand a chance of
being updated with the code.


Can we establish a list of classes and packages that are most urgently
in need of work?
Can we establish a list of classes that are fully documented ..... OK.  
How about "acceptably documented".


How can we handle the presentation and navigation of package level
documentation in the wiki? Does it go in the API list and show up when
you hit the plus sign in from of haXe.IO? Can this be done? That would
be my first choice.

I suppose that the tutorials are most likely to be best referenced from
the package level documentation as well as from the tutorial table of
contents.

Can we establish a list of tutorials that are up-to-date? I suspect that
most need to be reviewed for spelling, grammar and style.
Can we establish a list of tutorials that are required? I am sure that
everyone has a list.
Can we establish a list of tutorials that are in need of update or
serious work?

Can the management of this be done on the current wiki or should we have
a semi-private wiki where the administration of documentation can be
carried-on without scaring the casual haXe/Neko programmer?
This would include a section on style.
     Neko is always spelled with a "N" unless it is part of a class or
package name. Respect trademarks.
     haXe is always spelled with a "h" and a "X" unless it is part of a
class or package name. Respect trademarks.
    ASCII is a formal name and is not "ascii". Binary is not, so it is
not "BINARY".
    We'll agree that we aren't gonna use contractions or slang. It makes
reading too hard.
    We will try to keep sentences simple and short.
     If commas are required, use them.


Ron

David Bergman wrote:

> On Apr 15, 2009, at 1:40 PM, Zjnue Brzavi wrote:
>
>>> would adding all of this extra bulk to the stadard class files (full
>>> documentation in multi languages) have an effect on the speed of the
>>> compiler? i know that it *should* be minimal- but still
>>
>> Personally I would dread the sight of hefty comments in the code. It
>> is a delight to read NC's elegant and bloat-free code. A few guiding
>> comments may well help here and there, but my preference would be to
>> have them few and far between.
>
> We are talking about the haxedoc comments and, specifically, about the
> generated API documentation you get from such comments. Yes, I agree
> with you that too many naive comments in code is silly for those
> reading/maintaining code. But one should be able to understand what an
> API is doing without resorting to reading the code. So, we do need
> those haxedoc comments.
>
> In most Java projects, I try to have my team understand the
> distinction between pure code comments, helping out with the
> understanding of the code for maintainers (and wannabes :-) ), on one
> hand and the Javadoc/doxygen commnents, on the other hand, where the
> audience are the *users* of those classes/functions.
>
>> I think in order to cater for different preferences, it may help to
>> inject comments from other places (like the Wiki) instead, providing
>> parameters for preferred language(s), bulk level, etc..
>
> Well, we do have this tool haxedoc, and documentation in code
> (comments...) has a much greater chance of being accurate than
> externally edited documentation.
>
> We are not doing haxedoc a favor, market-wise, by only using it for
> some 50% of our own methods :-)
>
> /David
>


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

Re: About online API

David Bergman
On Apr 15, 2009, at 6:07 PM, Ron Wheeler wrote:

> I am not an expert on haxedoc. That being said, I will wade in anyway.
>
> 1) I hope that it can determine the difference between ordinary  
> comments and documentation.

Yes, it can. Only comments in "Javadoc"-blocks (/**   */) are read by  
haxedoc.

> 2) API documentation should not occur intermixed with code. It  
> should be in a block at the class level and in a block for each  
> method, above the method. This should not interfere with those  
> reading the code for sheer enjoyment but will be close enough to the  
> code to stand a chance of being updated with the code.

Agreed, and that is not a problem with haxedoc comments, which, just  
as with Javadoc and Doxygen, appear at the top of the method/class,  
just as you wanted it :-)

> Can we establish a list of classes and packages that are most  
> urgently in need of work?

My opinion is that "haxe.io" "haxe.remoting" are in dire need of  
documentation (or haxedoc comments) They should be documented to the  
level of "neko.io".

More later...

/David

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

Re: About online API

Zjnue Brzavi
In reply to this post by David Bergman
>>> would adding all of this extra bulk to the stadard class files (full
>>> documentation in multi languages) have an effect on the speed of the
>>> compiler? i know that it *should* be minimal- but still
>>
>> Personally I would dread the sight of hefty comments in the code. It
>> is a delight to read NC's elegant and bloat-free code. A few guiding
>> comments may well help here and there, but my preference would be to
>> have them few and far between.
>
> We are talking about the haxedoc comments and, specifically, about the
> generated API documentation you get from such comments. Yes, I agree with
> you that too many naive comments in code is silly for those
> reading/maintaining code. But one should be able to understand what an API
> is doing without resorting to reading the code. So, we do need those haxedoc
> comments.
>
> In most Java projects, I try to have my team understand the distinction
> between pure code comments, helping out with the understanding of the code
> for maintainers (and wannabes :-) ), on one hand and the Javadoc/doxygen
> commnents, on the other hand, where the audience are the *users* of those
> classes/functions.
>
>> I think in order to cater for different preferences, it may help to
>> inject comments from other places (like the Wiki) instead, providing
>> parameters for preferred language(s), bulk level, etc..
>
> Well, we do have this tool haxedoc, and documentation in code (comments...)
> has a much greater chance of being accurate than externally edited
> documentation.
>
> We are not doing haxedoc a favor, market-wise, by only using it for some 50%
> of our own methods :-)

Hi David,

Just a quick note - sorry to have dropped out of conversation. Time is
problematic right now, so perhaps I should not have made my quick
remark in the first place.

The basic idea I tried to propose is to have the ability to associate
different levels/types of comments for the same pieces of code (above
class and above methods).

..maybe using namespaces:

  [coder-light:doc]..[/coder-light:doc]
  [coder-verbose:doc]....[/coder-verbose:doc]
  [commercial:doc].......[/commercial:doc]

Then, have the ability to inject whichever ones you pick into the std
lib code you wish to ship / read.

For haxe.org/api, I think for non-edit mode, perhpas we could offer
different api display modes on the site itself. Having the adapted
haxedoc available to display all methods if preferred would also be
nice.

Of course this is all a long way off and getting existing wiki entries
up to standard is probably the correct first step as others suggested.
Also, please forgive suggestions that may sound arrogant - all just
time-constrained artifacts I hope.

All the best,
Zjnue

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

Re: About online API

Gamehaxe
In reply to this post by David Bergman
I think the only advantage of code-doc documentation
is that the doco and the code can be kept in sync by
the programmer who is making the changes.
But if the person who is changing the code is different
 from the one who is writing the doco, this advantage
is completely nullified, leaving it inferior in every way to a wiki.

Access: cvs  vs html
Syntax: indented comments  vs wiki markup
Multiple Langage: hard vs natural
Visibility: requires build step vs immediate
Code State: modified for non-coding purpose vs exactly as wanted

Now for every message that you have posted to this thread, go
and document 1 function in the wiki.  I did Graphics.clear,
and I may go through and do it Graphics a bit more systematically.
However, it is important to make a start with some action.

Hugh


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

Re: About online API

David Bergman
On Apr 16, 2009, at 8:14 AM, Hugh Sanderson wrote:

> I think the only advantage of code-doc documentation
> is that the doco and the code can be kept in sync by
> the programmer who is making the changes.

That is why one has code revision systems ;-)

> But if the person who is changing the code is different
> from the one who is writing the doco, this advantage
> is completely nullified, leaving it inferior in every way to a wiki.
>
> Access: cvs  vs html
> Syntax: indented comments  vs wiki markup
> Multiple Langage: hard vs natural
> Visibility: requires build step vs immediate
> Code State: modified for non-coding purpose vs exactly as wanted
>
> Now for every message that you have posted to this thread, go
> and document 1 function in the wiki.  I did Graphics.clear,
> and I may go through and do it Graphics a bit more systematically.
> However, it is important to make a start with some action.

I still think it is silly not to go to the core - the source code -  
for adding comments to the API (methods/classes), but I hear you, and  
will follow suite and make sure to push for reverse engineering it  
back to source code soon enough (totally ignoring the various  
platforms, which will present a problem down the road) :-)

/David

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