I think that they can go on the site in some way, but I just still don't
think we should check them in there.
If we are checking the stuff into SVN, we should probably do so local to
where generated (DRLVM docs in drlvm part of svn...) and just use svn
externals from the web site...
geir
Morozova, Nadezhda wrote:
So, do we want to actually commit the generated content into the
website
tree? I am kinda resistant to do so for reasons I can't defend very
well.
Well, the whole docset for drlvm only is ~5MB, with *many* pages empty
now. We can dream of times when all of them are in an ideal shape, but I
don't think it's realistic at this stage. If not, why have them?
Suggested compromise:
Have only the top-level interfaces documentation for DRLVM + classlib on
site with ability to generate all the rest locally.
For classlib, that could be kernels and vmi, for drlvm that could be
intercomponent - mostly located in the vm/include folder (see accurate
listing at
http://wiki.apache.org/harmony/DRLVM_Documentation_Interfaces_Classifica
tion
For a clearer view, I'd post the drlvm docs on my home. If we agree
these can go on site, would be great. Having a starting page for
interfaces code on the site would be marvelous too.
Cheers,
Nadya
-----Original Message-----
From: Geir Magnusson Jr. [mailto:[EMAIL PROTECTED]
Sent: Wednesday, November 29, 2006 8:16 PM
To: [email protected]
Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
Morozova, Nadezhda wrote:
So, the answer is "No" because it is not committed. Thanks, I know
the
JIRA. Aren't we ready to commit these?
Well,
Largely, yes, though the config file does not allow for class
hierarchy,
file lists and graphics. I hope Alexei can adjust the scripts to
check
for the graphviz dot tool required for class diagrams.
Anyway, the scripts will be in the svn soon; I was also planning to
generate the whole bundle and deposit on my home - just as Paulex did
yesterday.
So, do we want to actually commit the generated content into the
website
tree? I am kinda resistant to do so for reasons I can't defend very
well.
Certainly the scripts should be there...
geir
Cheers,
Nadya
-----Original Message-----
From: news [mailto:[EMAIL PROTECTED] On Behalf Of Egor Pasko
Sent: Wednesday, November 29, 2006 10:39 AM
To: [email protected]
Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
On the 0x22F day of Apache Harmony Nadezhda Morozova wrote:
BTW, do we have vm.cfg committed as well as all other stuff
necessary
to generate Doxygen docs?
Yes, see JIRA 2024 and download the doc.scripts.zip bundle. It has
the
build file, the vm.cfg for Doxygen and the doc.properties to feed
as
the
build targets.
Unload the files into the vm/doc/ directory and run ant. Should
work.
So, the answer is "No" because it is not committed. Thanks, I know
the
JIRA. Aren't we ready to commit these?
Cheers,
Nadya
-----Original Message-----
From: news [mailto:[EMAIL PROTECTED] On Behalf Of Egor Pasko
Sent: Tuesday, November 28, 2006 2:20 PM
To: [email protected]
Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
On the 0x22E day of Apache Harmony Nadezhda Morozova wrote:
Thanks for valuable feedback! We've got so many things to do.
u r welcome :)
I've used the key JIRA for Doxygen docs that we have now:
http://issues.apache.org/jira/browse/HARMONY-2024 submitted by
Alexei
F.
yes, I am looking in it too
There, we actually have two different doc sets:
Drlvm_intf_doc is for the whole bundle, and vm_doc.scripts.zip
enables
you to build component-wise documentation. Which one do we want?
I prefer *full docs* for all source files so I could travel
through
the docs where I want. So, drlvm_intf_doc..
I've been thinking of how to best add Doxygen docs to the
website,
suggest the following:
standard/site/xdocs/subcomponents/classlib/doxygen/index.html -
for
classlib bundle(s).
standard/site/xdocs/subcomponents/drlvm/doxygen/index.html - for
drlvm
bundle(s).
standard/site/xdocs/stylesheets/* - for the config files and
scripts
to
build Doxygen documentation.
Any objections?
Nadya, you have more expertise in this field :)
BTW, do we have vm.cfg committed as well as all other stuff
necessary
to generate Doxygen docs?
Cheers,
Nadya
-----Original Message-----
From: news [mailto:[EMAIL PROTECTED] On Behalf Of Egor Pasko
Sent: Monday, November 27, 2006 1:04 PM
To: [email protected]
Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
On the 0x22B day of Apache Harmony Alexei Fedotov wrote:
Ooops.... Sorry for incorrect word usage. I was intended to ask
who
will read Doxygen on our site and for which purpose. This would
help
us to understand what we should put there.
>From other projects I found Class hierarchy most useful in
Doxygen.
It
is also useful for beginners to see the top-level structure of
the
code in a comprehensive manner. See [1] as a live example of
on-site
doxygen in an opensource project.
I love to travel through the code in vim+ctags, but it is not
the
best
for all. So, I would vote for putting the Doxygen docs on the
site
as
it should be useful. The sooner the better because it should
help
people express their opinions on _what should be improved_.
Today
it
is not easy to say $subj if you do not see the docs out there..
have
to download 10MB, etc. etc.
I should have said that long ago.. but.. too busy, sorry :(
Today I downloaded th 10MB drlvm_intf_doc.zip and looking at it.
Some comments:
* header page is too brief
* no class hierarchy & class inheritance sexy pictures
* no source code browsing
* per-file view wastes a lot of space
Let's have the next step forward: put doxygen docs on the site!
And
regenerate them regularly (=as snapshots appear, for
example). How-to-improve opinions will come.
[1]
http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html
On 11/24/06, Alexei Fedotov <[EMAIL PROTECTED]> wrote:
All,
Let me support Nadya's request. The first thing we need to do
is
to
define what we are trying to achieve. Who is our target
auditory?
1. Egor said that he liked browsing object dependencies using
Doxygen.
2. Salikh said that he personally found browsing source files
much
more
useful.
3. All my cases are about situations when one programmer used
interfaces developed by another programmer.
Could you please share your experience with wonderful
Doxygen/javadooc
browsing?
--
Thank you,
Alexei
On 11/24/06, Morozova, Nadezhda <[EMAIL PROTECTED]>
wrote:
Hi,
I've tried out the scripts that build Doxygen docs for
DRLVM.
I
like
the
resulting input immensely, though further improvements
might
be
required
- will write specific suggestions later.
At this point, my key question is the following: How do we
want
to
organize our docs? Possible solutions:
- harmony_intf_doc: classlib + drlvm docs, one huge bundle.
Not sure it can work ok or be easy to maintain,
but...
- drlvm_intf_doc + classlib_intf_doc: two bundles;
drlvm_intf was submitted by Alexei to the same JIRA
-
can
use
as
a starting point.
- separate bundles for each big component/module inside
drlvm/classlib.
This is how Alexei's scripts work now.
To me, structuring into subdirs is fine. It helps browsing,
localizing
specific files, works marvelously for the wiki metrics
pages...
BUT!
With subdirs, you never get a full list of
files/funcs/structs/etc
for
the whole drlvm and if you search for a specific item,
you'll
have to
go
from bundle to bundle.
This can be partially fixed by an opening page with links
to
specific
component bundles. However, indexing and search would still
be
component-wise only.
There might be more arguments pro and contra. Everyone -
please
express
your preference!
PS: Alexei, thanks for a warm welcome, I'll work hard to
meet
your
expectations.
Cheers,
Nadya
-----Original Message-----
From: Alexei Fedotov [mailto:[EMAIL PROTECTED]
Sent: Friday, November 24, 2006 4:33 AM
To: [email protected]
Subject: Re: Re: [doc] What should be improved in DRLVM
Doxygen
documentation?
Nadya,
My congratulations with your new role. Now I believe
nothing
will
prevent Harmony web site and documentation from being the
best
and
the
coolest one. :-)
I have prepared a documentation update according Andrey's
Wiki
page
(with Egor's and Pavel's comments), see the last comment
to
http://issues.apache.org/jira/browse/HARMONY-2024. The
documentation
contains component bundles and inter-component interface
bundle.
If
you find results useful, please don't hesitate to ask
questions
about
how it works.
I also updated documentation metrics per bundle at the
Wiki
page:
http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
Many of .html files contain "The documentation for this
struct
was
generated from the following file:" footer, so it
shouldn't
be a
problem to understand which source file should be editied
to
improve
the metrics.
--
Thank you,
Alexei
On 11/21/06, Morozova, Nadezhda
<[EMAIL PROTECTED]>
wrote:
-----Original Message-----
From: news [mailto:[EMAIL PROTECTED] On Behalf Of
Egor
Pasko
Sent: Tuesday, November 21, 2006 7:42 AM
To: [email protected]
Subject: Re: [doc] What should be improved in DRLVM
Doxygen
documentation?
On the 0x227 day of Apache Harmony Nadezhda Morozova
wrote:
That's a great start. Yes, if we have such a table as
the
front
page
for
Doxygen interfaces, it would be great. If you wish, I
can
prepare
the
patch with the nice-looking version of it all.
Questions:
- When building Doxygen, can we have a target for
inter-
component
interfaces and for each component?
- if yes, should the files inside the include/
subfolder
be
built
with
the component they belong to?
- For VM core and jit: any ideas on how to group
files
further?
The
current list of files belonging to vm core interfaces
is
*so*
long...
- Should we prepare docs for gcv4?
IMO, the list of headers for Jitrino is too verbose.
For
inter-component picture I suggest the following subset:
vm/jitrino/src/dynopt/EdgeProfiler.h
vm/jitrino/src/dynopt/StaticProfiler.h
vm/jitrino/src/jet/jet.h
vm/jitrino/src/main/Jitrino.h
vm/jitrino/src/vm/drl/DrlEMInterface.h
vm/jitrino/src/vm/drl/DrlVMInterface.h
vm/jitrino/src/vm/EMInterface.h
vm/jitrino/src/vm/VMInterface.h
other headers are internal for Jitrino. So, the
suggestion
is: to
document the mapping between *relevant* h-files and the
structure
in
the DevGuide
[Nadya]
I think we're mixing two different header groups. The
first
type
is
*inter-component*, listed at the top of page on wiki.
The
devguide
shows
these interfaces in VM arch figure. As I understand,
these
are
the
interfaces that any jit must export:
Execution engine
JIT_VM
vm/include/internal_jit_intf.h
vm/include/open/ee_em_intf.h
Not sure how these are related to files
jitrino/src/vm/*Interface.h.
The other group is *Interfaces inside the components*.
Here
I
think
all
interfaces between internal parts of a component can go.
I
agree
JIT
and
VM core seem to have too many headers, but they are all
in
the
dir
tree.
Don't you think we need to document them?
My suggestion would be to add subgrouping for jit header
files
-
and
possibly assign priorities to different groups. What do
you
say?
Thank you,
Nadya Morozova
-----Original Message-----
From: Andrey Yakushev
[mailto:[EMAIL PROTECTED]
Sent: Monday, November 20, 2006 3:47 PM
To: [email protected]
Subject: Re: [doc] What should be improved in DRLVM
Doxygen
documentation?
In order to understand the mapping between h-files
and
structure
described in the Developers guide I have tried to
prepare
some
initial
classification. I put draft at
http://wiki.apache.org/harmony/DRLVM_Documentation_Interfaces_Classifi
c
atio
n.
Probably such tables could be added to Doxygen doc;
of
course
after
verification and rewriting it in more user friendly
manner.
Is this helpful?
Thanks,
Andrey
On 11/7/06, Mikhail Fursov <[EMAIL PROTECTED]>
wrote:
On 07 Nov 2006 21:17:45 +0600, Egor Pasko
<[EMAIL PROTECTED]>
wrote:
Do we feel that it is time to set
responsibilities
on
documenting
vm/include/* ?
+1 To start working on intercomponent interfaces.
Going
to
commit
a
couple
of EM interface files with documentation tomorrow.
I
do
not
believe
that
someday we will have all component's local code
documented
(-1
to
make
such
policy for patches), but intercomponent
documentation
is
something
we
must
have (actually we must not only document but clean
the
code
too)
--
Mikhail Fursov
--
Egor Pasko
--
Thank you,
Alexei
--
Egor Pasko
--
Egor Pasko
--
Egor Pasko
