Useful documentation was: Truffle repository conversion

[Jaroslav Tulach]

On Monday, June 29, 2015 08:32:54 PM Stefan Marr wrote:
> Hi Andreas:
> 
> Just to piggy-back onto the mail.
> 
> Would be great if the repo could have a useful README with pointers to
> SimpleLanguage, relevant documentation, etc.

Yes, you are right the documentation is in poor shape. I already started some 
efforts to make it better[1], however I never know what to do sooner: fix the 
actual API/code or improve the documentation? Hopefully in a few weeks the API 
will be in a shape where it will only need documentation improvements.

Anyway what I'd like to have is a daily updated Javadoc for current 
development version. The javadoc shall only list packages that contain API 
(and hide all other implementation stuff). There shall be an overview page and 
package description pages giving useful entry points into the actual types 
that matter for most common use-cases. The Javadoc should be at least as good 
as HTML/Java documentation[2] which I worked on in last few years.

In a few months I'd like to also establish a change tracking system, so we can 
automatically generate "What's new pages" (similar to NetBeans apichange 
lists[3]) with every release of Truffle.

> I could lend a hand with that.

That would be more than welcomed. A fix to API documentation is at least as 
important as fix to the actual code.
-jt

[1] http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/ff6f34159b8a
[2] http://bits.netbeans.org/html+java/
[3] http://bits.netbeans.org/8.0/javadoc/apichanges.html
 
> PS: Splitting out the repo is going to help me with my workflow, I think.
> But, haven’t actually updated Graal/Truffle in the last 3 weeks…
> > On 29 Jun 2015, at 20:22, Andreas Woess <andreas.woess at oracle.com> wrote:
> > 
> > Dear Truffle developers and users,
> > 
> > we've recently moved Truffle to a separate repository as announced
> > earlier. I'd like to give you a heads-up that we're going to: (a) rewrite
> > the changeset history to prune unrelated files inherited from the
> > previous repository and shrink the repository size (b) change the
> > directory structure to mx2 layout, i.e., the 'truffle' directory will go
> > away
> > 
> > As a consequence, you will have to reclone the repository once the
> > conversion is done; but more importantly, if you have unpushed changes or
> > patches, please try to get them in within the next days while we wait for
> > the dust to settle. If you need more time or help with the migration, let
> > me know. If you're only using .jar files, you're not affected.
> > 
> > - andreas