haXe API documentation

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

haXe API documentation

K. Jones
The documentation for the haXe, flash, neko and other APIs on the
site/wiki and included with the complier seem a bit thin. All of the
functions, properties, and constants for the classes don't have any
description at all, which makes them a bit hard to use when you aren't
sure what they do. Is there some reason its like this?

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

Re: haXe API documentation

James W. Hofmann
Quoting " K. Jones" <[hidden email]>:

> The documentation for the haXe, flash, neko and other APIs on the
> site/wiki and included with the complier seem a bit thin. All of the
> functions, properties, and constants for the classes don't have any
> description at all, which makes them a bit hard to use when you aren't
> sure what they do. Is there some reason its like this?
>
> --
> haXe - an open source web programming language
> http://haxe.org
>

The API docs are auto-generated from haxedoc, I think. So except where  
the API source gets commented with haxedoc comments it'll be empty.  
This is a bad excuse but in any case working around it depends on the  
API you are using.

For Flash this is not so bad as the functions map to what is listed in  
the Adobe AS2/AS3 APIs. Neko also has an API that is described with  
more detail in the nekovm docs. HaXe-crossplatform stuff is described  
across various wiki pages. JS and PHP are just weird, IMHO :P


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

Re: haXe API documentation

Ian Martins

James Hofmann wrote:

> Quoting " K. Jones" <[hidden email]>:
>
>> The documentation for the haXe, flash, neko and other APIs on the
>> site/wiki and included with the complier seem a bit thin. All of the
>> functions, properties, and constants for the classes don't have any
>> description at all, which makes them a bit hard to use when you aren't
>> sure what they do. Is there some reason its like this?
>>
>> --
>> haXe - an open source web programming language
>> http://haxe.org
>>
>
> The API docs are auto-generated from haxedoc, I think. So except where
> the API source gets commented with haxedoc comments it'll be empty.
> This is a bad excuse but in any case working around it depends on the
> API you are using.
>
> For Flash this is not so bad as the functions map to what is listed in
> the Adobe AS2/AS3 APIs. Neko also has an API that is described with
> more detail in the nekovm docs. HaXe-crossplatform stuff is described
> across various wiki pages. JS and PHP are just weird, IMHO :P
>
>
the api docs were originally generated from haxedoc, but are now a wiki
independent from the source.  much of it is blank because no one's
filled it in.  it's not true that nothing is documented, though.  
actually I figured out a while ago that 48% of the neko and
crossplatform api are documented.

if you want to find out how something works the available resources are:
this mailing list and its archive, the wiki tutorials, lee and franco's
book, the haxe sources.

-Ian

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

Re: haXe API documentation

David Bergman
In reply to this post by K. Jones
My guess to the reason: Nicolas is only human, albeit a genius  
specimen, and time spent on documenting has been spent on creating  
this masterpiece which is haXe (and I am not even mentioning  
Neko...) ;-)

If we had write access to the CVS (ugh...) repository, we could start  
at least adding extractable documentation and promise on our stack of  
Jolt Cola that we will not touch anything else ;-)

NOTE: I belong to another school w.r.t. documenting in code, and  
*always* document thorougly, as I am almost literate (in the Knuth  
sense...), but I have not created a masterpiece like haXe, on the  
other hand...

/David

On Apr 12, 2009, at 2:40 AM, K. Jones wrote:

> The documentation for the haXe, flash, neko and other APIs on the
> site/wiki and included with the complier seem a bit thin. All of the
> functions, properties, and constants for the classes don't have any
> description at all, which makes them a bit hard to use when you aren't
> sure what they do. Is there some reason its like this?
>
> --
> 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 API documentation

David Bergman
I realize that the Wiki could be out-of-sync with the haxedoc:ed  
documentation, which would make our efforts easier: just run it  
ourselves and change the Wiki pages! It could also mean that my school  
is not that different from Nicolas' :-|

Will dive into the code much more before I differentiate  
methodologies. Sorry.

/David

On Apr 12, 2009, at 9:16 PM, David Bergman wrote:

> My guess to the reason: Nicolas is only human, albeit a genius  
> specimen, and time spent on documenting has been spent on creating  
> this masterpiece which is haXe (and I am not even mentioning  
> Neko...) ;-)
>
> If we had write access to the CVS (ugh...) repository, we could  
> start at least adding extractable documentation and promise on our  
> stack of Jolt Cola that we will not touch anything else ;-)
>
> NOTE: I belong to another school w.r.t. documenting in code, and  
> *always* document thorougly, as I am almost literate (in the Knuth  
> sense...), but I have not created a masterpiece like haXe, on the  
> other hand...
>
> /David
>
> On Apr 12, 2009, at 2:40 AM, K. Jones wrote:
>
>> The documentation for the haXe, flash, neko and other APIs on the
>> site/wiki and included with the complier seem a bit thin. All of the
>> functions, properties, and constants for the classes don't have any
>> description at all, which makes them a bit hard to use when you  
>> aren't
>> sure what they do. Is there some reason its like this?
>>
>> --
>> 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 API documentation

Nicolas Cannasse
In reply to this post by K. Jones
  K. Jones a écrit :
> The documentation for the haXe, flash, neko and other APIs on the
> site/wiki and included with the complier seem a bit thin. All of the
> functions, properties, and constants for the classes don't have any
> description at all, which makes them a bit hard to use when you aren't
> sure what they do. Is there some reason its like this?

While the original documentation has been extracted from the sources, it
can safely be completed by editing the Wiki, since the API
synchronization which is done when a new version is released keep the
Wiki documentation if available.

Out of curiosity, which API did you find not understandable ?

BTW if anybody feels like completing the missing API documentation,
please edit the Wiki. The only thing that can't be done is to copy/paste
an existing copyrighted documentation, such as the one provided by Adobe
for the flash.* package.

Nicolas

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

Re: haXe API documentation

Ron Wheeler
Nicolas Cannasse wrote:

>  K. Jones a écrit :
>> The documentation for the haXe, flash, neko and other APIs on the
>> site/wiki and included with the complier seem a bit thin. All of the
>> functions, properties, and constants for the classes don't have any
>> description at all, which makes them a bit hard to use when you aren't
>> sure what they do. Is there some reason its like this?
>
> While the original documentation has been extracted from the sources,
> it can safely be completed by editing the Wiki, since the API
> synchronization which is done when a new version is released keep the
> Wiki documentation if available.
>
> Out of curiosity, which API did you find not understandable ?
>
> BTW if anybody feels like completing the missing API documentation,
> please edit the Wiki. The only thing that can't be done is to
> copy/paste an existing copyrighted documentation, such as the one
> provided by Adobe for the flash.* package.
>
> Nicolas
>
Am I looking in the right place?
If one goes to haxe.org and clicks on API and goes to Haxe=>Remoting,
one finds methods with no description at all.
I am not sure if that is "confusing" (there is no text to read and
misunderstand) but it is not helpful at all.

I checked a few other classes and they were even less helpful - many did
not list any methods.

Is it not possible to extract the documentation from the code (javadocs,
doxygen, etc.) ?


Ron


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

Re: haXe API documentation

Ian Martins
Ron Wheeler wrote:

> Nicolas Cannasse wrote:
>>  K. Jones a écrit :
>>> The documentation for the haXe, flash, neko and other APIs on the
>>> site/wiki and included with the complier seem a bit thin. All of the
>>> functions, properties, and constants for the classes don't have any
>>> description at all, which makes them a bit hard to use when you aren't
>>> sure what they do. Is there some reason its like this?
>>
>> While the original documentation has been extracted from the sources,
>> it can safely be completed by editing the Wiki, since the API
>> synchronization which is done when a new version is released keep the
>> Wiki documentation if available.
>>
>> Out of curiosity, which API did you find not understandable ?
>>
>> BTW if anybody feels like completing the missing API documentation,
>> please edit the Wiki. The only thing that can't be done is to
>> copy/paste an existing copyrighted documentation, such as the one
>> provided by Adobe for the flash.* package.
>>
>> Nicolas
>>
> Am I looking in the right place?
> If one goes to haxe.org and clicks on API and goes to Haxe=>Remoting,
> one finds methods with no description at all.
> I am not sure if that is "confusing" (there is no text to read and
> misunderstand) but it is not helpful at all.
>
> I checked a few other classes and they were even less helpful - many
> did not list any methods.
>
> Is it not possible to extract the documentation from the code
> (javadocs, doxygen, etc.) ?
the ones that don't list any methods probably don't have any methods.  
the documentation that's there was extracted from the code using
something analogous to javadoc or doxygen.  look at the crossplatform
classes for examples of documentation.

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

Re: haXe API documentation

James W. Hofmann
Quoting "Ian Martins" <[hidden email]>:

> Ron Wheeler wrote:
>> Nicolas Cannasse wrote:
>>> K. Jones a écrit :
>>>> The documentation for the haXe, flash, neko and other APIs on the
>>>> site/wiki and included with the complier seem a bit thin. All of the
>>>> functions, properties, and constants for the classes don't have any
>>>> description at all, which makes them a bit hard to use when you aren't
>>>> sure what they do. Is there some reason its like this?
>>>
>>> While the original documentation has been extracted from the  
>>> sources, it can safely be completed by editing the Wiki, since the  
>>> API synchronization which is done when a new version is released  
>>> keep the Wiki documentation if available.
>>>
>>> Out of curiosity, which API did you find not understandable ?
>>>
>>> BTW if anybody feels like completing the missing API  
>>> documentation, please edit the Wiki. The only thing that can't be  
>>> done is to copy/paste an existing copyrighted documentation, such  
>>> as the one provided by Adobe for the flash.* package.
>>>
>>> Nicolas
>>>
>> Am I looking in the right place?
>> If one goes to haxe.org and clicks on API and goes to  
>> Haxe=>Remoting, one finds methods with no description at all.
>> I am not sure if that is "confusing" (there is no text to read and  
>> misunderstand) but it is not helpful at all.
>>
>> I checked a few other classes and they were even less helpful -  
>> many did not list any methods.
>>
>> Is it not possible to extract the documentation from the code  
>> (javadocs, doxygen, etc.) ?
> the ones that don't list any methods probably don't have any methods.

That's answering the wrong question.

Remoting docs can be found here:
http://haxe.org/doc/remoting

When the API is suspiciously lacking docs that means a tutorial is  
buried elsewhere in the wiki.


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

Re: haXe API documentation

Ron Wheeler
In reply to this post by Ian Martins
Ian Martins wrote:

> Ron Wheeler wrote:
>> Nicolas Cannasse wrote:
>>>  K. Jones a écrit :
>>>> The documentation for the haXe, flash, neko and other APIs on the
>>>> site/wiki and included with the complier seem a bit thin. All of the
>>>> functions, properties, and constants for the classes don't have any
>>>> description at all, which makes them a bit hard to use when you aren't
>>>> sure what they do. Is there some reason its like this?
>>>
>>> While the original documentation has been extracted from the
>>> sources, it can safely be completed by editing the Wiki, since the
>>> API synchronization which is done when a new version is released
>>> keep the Wiki documentation if available.
>>>
>>> Out of curiosity, which API did you find not understandable ?
>>>
>>> BTW if anybody feels like completing the missing API documentation,
>>> please edit the Wiki. The only thing that can't be done is to
>>> copy/paste an existing copyrighted documentation, such as the one
>>> provided by Adobe for the flash.* package.
>>>
>>> Nicolas
>>>
>> Am I looking in the right place?
>> If one goes to haxe.org and clicks on API and goes to Haxe=>Remoting,
>> one finds methods with no description at all.
>> I am not sure if that is "confusing" (there is no text to read and
>> misunderstand) but it is not helpful at all.
>>
>> I checked a few other classes and they were even less helpful - many
>> did not list any methods.
>>
>> Is it not possible to extract the documentation from the code
>> (javadocs, doxygen, etc.) ?
> the ones that don't list any methods probably don't have any methods.  
> the documentation that's there was extracted from the code using
> something analogous to javadoc or doxygen.  look at the crossplatform
> classes for examples of documentation.
>

http://www.haxe.org/api/haxe/remoting/httpconnection
Is pretty much a waste of a page.

http://www.haxe.org/api/haxe/remoting/flashjsconnection 
Same

http://www.haxe.org/api/datetools
Reasonable documentation but very incomplete.
"static function format( d : Date <http://www.haxe.org/api/date>, f :
String <http://www.haxe.org/api/string> ) : String
<http://www.haxe.org/api/string> Format the date |d| according to the
format |f|. The format is compatible with the |strftime| standard
format, except that there is no support in Flash and JS for day and
months names (due to lack of proper internationalization API). On
haXe/Neko/Windows, some formats are not supported."
 - No link to strftime - what is this? What does compatible mean?
 - "some formats are not supported" - which ones? Does anyone know? Is
there a list?




It would be nice if one could write all of one's code using only classes
with documentation but my designs are never done using such a constraint.

Would it be a good place to start the documentation project by fixing
the source code to have better documentation?


I like the ideas about examples and perhaps the source code could even
reference examples so that the generated docs were really well
integrated with the manually prepared documentation.
I know that this concept will make the programmers of the API initially
uncomfortable (What if the wiki changes or an example disappears?) but
in reality, the documentation can be as stable as the code, if we want
it to be.
The people writing and organizing the manual documentation will have to
be as constrained by upwards compatibility as the API's programmers are.
"If you want to change the structure of the documentation, you have to
be aware of the cost to change the API's comments and be prepared to do
it." The programmers will have to be aware that if they change the
functionality so that the docs are wrong, they have to change the docs too.

Perhaps there is a way to provide a fixed reference point that the API
documentation can refer to that will be mapped to the correct URL of the
manually generated documentation or to a "Sorry, we screwed up page" if
we have left a link in the API that has been removed or changed in the
manually generated documentation.



Ron

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

Re: haXe API documentation

Ron Wheeler
In reply to this post by James W. Hofmann
James Hofmann wrote:

> Quoting "Ian Martins" <[hidden email]>:
>
>> Ron Wheeler wrote:
>>> Nicolas Cannasse wrote:
>>>> K. Jones a écrit :
>>>>> The documentation for the haXe, flash, neko and other APIs on the
>>>>> site/wiki and included with the complier seem a bit thin. All of the
>>>>> functions, properties, and constants for the classes don't have any
>>>>> description at all, which makes them a bit hard to use when you
>>>>> aren't
>>>>> sure what they do. Is there some reason its like this?
>>>>
>>>> While the original documentation has been extracted from the
>>>> sources, it can safely be completed by editing the Wiki, since the
>>>> API synchronization which is done when a new version is released
>>>> keep the Wiki documentation if available.
>>>>
>>>> Out of curiosity, which API did you find not understandable ?
>>>>
>>>> BTW if anybody feels like completing the missing API documentation,
>>>> please edit the Wiki. The only thing that can't be done is to
>>>> copy/paste an existing copyrighted documentation, such as the one
>>>> provided by Adobe for the flash.* package.
>>>>
>>>> Nicolas
>>>>
>>> Am I looking in the right place?
>>> If one goes to haxe.org and clicks on API and goes to
>>> Haxe=>Remoting, one finds methods with no description at all.
>>> I am not sure if that is "confusing" (there is no text to read and
>>> misunderstand) but it is not helpful at all.
>>>
>>> I checked a few other classes and they were even less helpful - many
>>> did not list any methods.
>>>
>>> Is it not possible to extract the documentation from the code
>>> (javadocs, doxygen, etc.) ?
>> the ones that don't list any methods probably don't have any methods.
>
> That's answering the wrong question.
>
> Remoting docs can be found here:
> http://haxe.org/doc/remoting
>
> When the API is suspiciously lacking docs that means a tutorial is
> buried elsewhere in the wiki.
>
>
I do not find that acceptable in a professional product.
The API should be fully descriptive of the class and its methods.

The tutorials show one or two ways in which the class can be used.
These are completely different things.
The tutorials are not obliged to use every method of the class nor to
describe in detail what each of the parameters could mean outside of the
context of the tutorial.


Ron


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

Re: haXe API documentation

Hudson Ansley
On Tue, Apr 14, 2009 at 1:22 PM, Ron Wheeler
<[hidden email]> wrote:
> I do not find that acceptable in a professional product.

umm, I guess HaXe is technically *not* a "professional product", i.e.,
I don't think Nicolas or MotionTwin make any money off it directly;
they don't even have a "donate" button on the site last time I
checked. It is more like an "amazing gift" ;-)  Of course a lot of
people are finding they are able to make money using it. BTW- anybody
can add to and improve the documentation...

There is this book:
http://www.amazon.com/Professional-haXe-Neko-Programmer/dp/0470122137

although it needs an update :-)

Regards,
Hudson

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

Re: haXe API documentation

Robin Palotai
Haxe aims for a complete client-server solution. As I understood, haXe
drives quite a big part of technology behind Motion-Twin, so it sure
is a professional product.

The lack of documentation disturbed me too, but I only used flash api
this far, so I could easily solve by looking up the adobe livedocs.
However, if the neko/etc documentation is such leaky, it might be more
disturbing.

I support adding detailed documentation to everywhere, once we figure
out how to do that (since haxe version updates will overwrite the api
docs on the wiki, ifI remember correctly)

Robin

> umm, I guess HaXe is technically *not* a "professional product", i.e.,
> I don't think Nicolas or MotionTwin make any money off it directly;

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

Re: haXe API documentation

Hudson Ansley
On Tue, Apr 14, 2009 at 4:15 PM, Robin Palotai <[hidden email]> wrote:
> Haxe aims for a complete client-server solution. As I understood, haXe
> drives quite a big part of technology behind Motion-Twin, so it sure
> is a professional product.

you could certainly call it a professional tool. I think product in
this context implies it is being sold or generates money directly, but
I guess that is being a bit narrow... which is why I said
"technically" :-)

>
> I support adding detailed documentation to everywhere, once we figure
> out how to do that (since haxe version updates will overwrite the api
> docs on the wiki, ifI remember correctly)
>
that's a good point. Would be good to have a solution for that
(assuming it is still the case). I guess you could edit the comments
in the code directly, but kind of makes the wiki part of it
pointless... and it is not as simple to do. At the least sections of
the wiki should be made read-only if they are just going to get
overwritten...

Regards,
Hudson

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

Re: haXe API documentation

Nicolas Cannasse
In reply to this post by Robin Palotai
> I support adding detailed documentation to everywhere, once we figure
> out how to do that (since haxe version updates will overwrite the api
> docs on the wiki, ifI remember correctly)

Not it doesn't, the Wiki documentation is kept even after synchronization.

Nicolas

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

Re: haXe API documentation

David Bergman
On Apr 14, 2009, at 4:58 PM, Nicolas Cannasse wrote:

>> I support adding detailed documentation to everywhere, once we figure
>> out how to do that (since haxe version updates will overwrite the api
>> docs on the wiki, ifI remember correctly)
>
> Not it doesn't, the Wiki documentation is kept even after  
> synchronization.

Hmm, the API documentation should always be a straight haxedoc  
extraction from current (trunk or latest stable release), since manual  
changes to the Wiki page would definitely be lost when somebody decide  
to update the API documentation to reflect haXe 2.1...

In fact, the API documentation portion of the haXe site should not be  
a Wiki at all, but rather automatically extracted (with haxedoc) and  
uploaded as part of an continuous integration process - upon success -  
or at least with a simple command-line tool, and then read-only on site.

The problem is that some complex parts of the API is not documented  
(in-code) at all, such as the haxe.remoting package.

How can I help in this effort, of

1. properly adorning the code with haxedoc comments - I could always  
do it locally, versus HEAD as of some specific time, but there would  
be merging required of that (informal branch, in terms of a bunch of  
patches...) since the HEAD of trunk will move during that effort

2. making the API part of the site automatically synchronized with the  
haxedoced trunk (or a specific version) and outside the regular Wiki  
access sphere/flow?

?

Or, is that the wrong approach?

/David

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

Re: haXe API documentation

Ian Martins
David Bergman wrote:

> On Apr 14, 2009, at 4:58 PM, Nicolas Cannasse wrote:
>
>>> I support adding detailed documentation to everywhere, once we figure
>>> out how to do that (since haxe version updates will overwrite the api
>>> docs on the wiki, ifI remember correctly)
>>
>> Not it doesn't, the Wiki documentation is kept even after
>> synchronization.
>
> How can I help in this effort, of
>
> 1. properly adorning the code with haxedoc comments - I could always
> do it locally, versus HEAD as of some specific time, but there would
> be merging required of that (informal branch, in terms of a bunch of
> patches...) since the HEAD of trunk will move during that effort
I did this before.
http://markmail.org/message/jfw6gwfx2a4f6aod

-Ian

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

Re: haXe API documentation

David Bergman
On Apr 14, 2009, at 7:00 PM, Ian Martins wrote:

> David Bergman wrote:
>> On Apr 14, 2009, at 4:58 PM, Nicolas Cannasse wrote:
>>
>>>> I support adding detailed documentation to everywhere, once we  
>>>> figure
>>>> out how to do that (since haxe version updates will overwrite the  
>>>> api
>>>> docs on the wiki, ifI remember correctly)
>>>
>>> Not it doesn't, the Wiki documentation is kept even after  
>>> synchronization.
>>
>> How can I help in this effort, of
>>
>> 1. properly adorning the code with haxedoc comments - I could  
>> always do it locally, versus HEAD as of some specific time, but  
>> there would be merging required of that (informal branch, in terms  
>> of a bunch of patches...) since the HEAD of trunk will move during  
>> that effort
> I did this before.
> http://markmail.org/message/jfw6gwfx2a4f6aod

So, your tool did what?

Did it extract stuff that people might have entered on the Wiki pages  
(under the API sub site) and create diffs for those, relative some  
point (revision 1.34 in that specific case)?

I.e., a tool to reverse engineer the comments back into the code?

Just so I understand.

Is that the most proper way forward?

I assumed going to the source (pun intended...) was the best route  
forward, i.e., actually changing the haxedoc parts of the code and  
having the API Wiki become a passive reflector for those comments. The  
duality, sort of, of what your tool (and the Wiki editing efforts)  
achieves.

/David

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

Re: haXe API documentation

James W. Hofmann
In reply to this post by Nicolas Cannasse
Quoting "Nicolas Cannasse" <[hidden email]>:

>> I support adding detailed documentation to everywhere, once we figure
>> out how to do that (since haxe version updates will overwrite the api
>> docs on the wiki, ifI remember correctly)
>
> Not it doesn't, the Wiki documentation is kept even after synchronization.
>
> Nicolas
>

I've edited the wiki API pages before and I don't think my edits were  
preserved, but it was a long time ago. Did something about this  
process change?

Also, are the wiki pages used for compiling the offline documentation?  
If not, they should.


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

Re: haXe API documentation

Ian Martins
In reply to this post by David Bergman
David Bergman wrote:

> On Apr 14, 2009, at 7:00 PM, Ian Martins wrote:
>
>> David Bergman wrote:
>>> On Apr 14, 2009, at 4:58 PM, Nicolas Cannasse wrote:
>>>
>>>>> I support adding detailed documentation to everywhere, once we figure
>>>>> out how to do that (since haxe version updates will overwrite the api
>>>>> docs on the wiki, ifI remember correctly)
>>>>
>>>> Not it doesn't, the Wiki documentation is kept even after
>>>> synchronization.
>>>
>>> How can I help in this effort, of
>>>
>>> 1. properly adorning the code with haxedoc comments - I could always
>>> do it locally, versus HEAD as of some specific time, but there would
>>> be merging required of that (informal branch, in terms of a bunch of
>>> patches...) since the HEAD of trunk will move during that effort
>> I did this before.
>> http://markmail.org/message/jfw6gwfx2a4f6aod
>
> So, your tool did what?
>
> Did it extract stuff that people might have entered on the Wiki pages
> (under the API sub site) and create diffs for those, relative some
> point (revision 1.34 in that specific case)?
>
> I.e., a tool to reverse engineer the comments back into the code?
yes, basically, but it directly modified the local source tree (whatever
version you currently have).  I just created the patch to send to the list.

it was a quick and dirty program that I wrote in a day.  it doesn't
handle all cases, so I had to do some hand edits.  just to say it isn't
fully-automatic.



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