[drlvm][doc] missing starting pages for Doxygen docs

["Morozova, Nadezhda" <na...@intel.com>]

Hi all,
I'm concerned that the Doxygen docs we're building from source code [1]
don't have overview pages to say exactly what the documentation
includes, no kind of intro (with the exception of DRLVM external intf
bundle [2].

I opened HARMONY-3432 to fix that. I can try to create the overview
pages for some modules. Your help is needed to (a) decide where to
locate the new files, (b) review the overviews and (c) write the ones I
cannot write due to lack of understanding/expertise. 

About (c) file locations, please express your opinions on the following
locations for mainpage.html that will be starting pages for
component-specific documentation bundles:
em/src
gc_cc/
gc_gen/src
include/open (already there)
interpreter/src
jitrino/src
port/ or port/doc? port/src?
tests/
thread/doc/ or thread/? or thread/src?
vmcore/src
vmi/src
vmstart/src

Cheers, Nadya

[1] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
[2]
http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.ht
ml
[3] https://issues.apache.org/jira/browse/HARMONY-3432

RE: [drlvm][doc] missing starting pages for Doxygen docs

["Morozova, Nadezhda" <na...@intel.com>]

Andrey,
Thanks for input. 
>What kind of mainpages are you going to add, interface or
>implementation description?
I planned to stick with interface descriptions for now. I've taken a
look at the vmcore mainpage file that you posted, and I think we're
moving in the right direction. Unfortunately, I am not familiar with all
the modules to be able to sort out interfaces like that, but I'll add
the placeholder descriptions with the generic text and then we could go
from one to another and improve them. I'll post a patch to JIRA
HARMONY-3432 for your review. 

Cheers, 
Nadya
 

>-----Original Message-----
>From: Andrey Yakushev [mailto:andrey.yakushev@gmail.com]
>Sent: Thursday, March 22, 2007 6:29 PM
>To: dev@harmony.apache.org
>Subject: Re: [drlvm][doc] missing starting pages for Doxygen docs
>
>Now mainpages exist inside:
>    vm\jitrino\src\jet\jet.cpp
>    vm\include\open\mainpage.html
>    vm\tests\unit\framework\testframe.h
>
>icu4c for example uses separate *.h file for mainpage:
>    working_classlib\deploy\include\icu4c\unicode\docmain.h
>
>mainpage.html was added by me. I was going to use separate file like
>icu4c did, but I used extension .html instead of .h in order to permit
>easier editing inside Visual Studio. It could be renamed to .h if
>needed.
>
>I think that mainpage for source code documentation should be placed
>together with the source (so no /doc folders) but I suggest don't
>unify it placement. Let it be in include/ (for interfaces
>description), in src/ (for implementation description or for
>interfaces description if module doesn't have separate include/
>folder), in some .h, .c, .cpp etc. or in a separate file as
>appropriate for the particular module.
>
>What kind of mainpages are you going to add, interface or
>implementation description?
>
>Thanks,
>Andrey
>
>
>On 3/22/07, Morozova, Nadezhda <na...@intel.com> wrote:
>>
>> Hi all,
>> I'm concerned that the Doxygen docs we're building from source code
[1]
>> don't have overview pages to say exactly what the documentation
>> includes, no kind of intro (with the exception of DRLVM external intf
>> bundle [2].
>>
>> I opened HARMONY-3432 to fix that. I can try to create the overview
>> pages for some modules. Your help is needed to (a) decide where to
>> locate the new files, (b) review the overviews and (c) write the ones
I
>> cannot write due to lack of understanding/expertise.
>>
>> About (c) file locations, please express your opinions on the
following
>> locations for mainpage.html that will be starting pages for
>> component-specific documentation bundles:
>> em/src
>> gc_cc/
>> gc_gen/src
>> include/open (already there)
>> interpreter/src
>> jitrino/src
>> port/ or port/doc? port/src?
>> tests/
>> thread/doc/ or thread/? or thread/src?
>> vmcore/src
>> vmi/src
>> vmstart/src
>>
>> Cheers, Nadya
>>
>> [1] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
>> [2]
>>
http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.ht
>> ml
>> [3] https://issues.apache.org/jira/browse/HARMONY-3432
>>

Re: [drlvm][doc] missing starting pages for Doxygen docs

[Andrey Yakushev <an...@gmail.com>]

Now mainpages exist inside:
    vm\jitrino\src\jet\jet.cpp
    vm\include\open\mainpage.html
    vm\tests\unit\framework\testframe.h

icu4c for example uses separate *.h file for mainpage:
    working_classlib\deploy\include\icu4c\unicode\docmain.h

mainpage.html was added by me. I was going to use separate file like
icu4c did, but I used extension .html instead of .h in order to permit
easier editing inside Visual Studio. It could be renamed to .h if
needed.

I think that mainpage for source code documentation should be placed
together with the source (so no /doc folders) but I suggest don't
unify it placement. Let it be in include/ (for interfaces
description), in src/ (for implementation description or for
interfaces description if module doesn't have separate include/
folder), in some .h, .c, .cpp etc. or in a separate file as
appropriate for the particular module.

What kind of mainpages are you going to add, interface or
implementation description?

Thanks,
Andrey


On 3/22/07, Morozova, Nadezhda <na...@intel.com> wrote:
>
> Hi all,
> I'm concerned that the Doxygen docs we're building from source code [1]
> don't have overview pages to say exactly what the documentation
> includes, no kind of intro (with the exception of DRLVM external intf
> bundle [2].
>
> I opened HARMONY-3432 to fix that. I can try to create the overview
> pages for some modules. Your help is needed to (a) decide where to
> locate the new files, (b) review the overviews and (c) write the ones I
> cannot write due to lack of understanding/expertise.
>
> About (c) file locations, please express your opinions on the following
> locations for mainpage.html that will be starting pages for
> component-specific documentation bundles:
> em/src
> gc_cc/
> gc_gen/src
> include/open (already there)
> interpreter/src
> jitrino/src
> port/ or port/doc? port/src?
> tests/
> thread/doc/ or thread/? or thread/src?
> vmcore/src
> vmi/src
> vmstart/src
>
> Cheers, Nadya
>
> [1] http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html
> [2]
> http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.ht
> ml
> [3] https://issues.apache.org/jira/browse/HARMONY-3432
>