Re: [doc] A better javadoc?

[Nadya Morozova <na...@googlemail.com>]

Tim,

I won't get your hopes too high, but if you really need this, I can play
some tricks to make these docs more readable by:
- adding styles to color- and font-separate parts of info
- adding a TOC on the left instead of those tabs, TOC can be a drop-down
menu which also acts as a list of classes
- adding a small frame which shows members of a class and each member on a
separate page instead of all functions on one page (i have only done this
for C code so far, but Java should also be ok)
- looking at current markup and suggesting changes that Doxygen would
understand better (we could then accumulate those changes and make them a
cleanup script; it won't always work because diff authors use diff markups,
but some things it'll fix for sure)
- i don't know, play some more...

On Jan 31, 2008 8:18 PM, Tim Ellison <t....@gmail.com> wrote:

> Nadya Morozova wrote:
> > I won't say I'm a vigorous fan of Doxygen for fear of being disliked by
> Java
> > programmers, but I think a tool that parses both C and Java code is
> > preferable for a project that has both. I've used Doxygen for a while
> now,
> > and although some things might get tricky and you have to do stupid
> things
> > to have output your way, Doxygen is generally rather good. My expertise
> is a
> > bit more limited in regard to Javadoc.
>
> That's cool, I know you are a documentation wizz <g>.  What sort of
> thing do you think we can do with the code comments we have got already?
>
> > Perhaps, if you gave specific examples of what you want to achieve, i'd
> say
> > whether and how it could be done.
>
> Make it usable, and pretty :-)
>
> > I don't know any freeware auto-generation
> > tools that do as good as these two. I've wanted to use a commercial tool
> > DocOMatic on a different project (just out of curiosity, why do they
> want us
> > to pay $1000 for it?) - but failed, because the tool had no free trial!
> >
> > Anyway, to the best of my knowledge, we don't have much choice in API
> > documentation generation tools. We could tweak the existing tools,
> and/or
> > post-process the resulting docs to get the results we want.
> > I'd be happy to see somebody prove me wrong, so that we get a better
> tool
> > for our docs.
>
> Ah well, I guess we have to keep banging sticks and rocks together for
> the time being.
>
> Regards,
> Tim
>



-- 
Cheers,
Nadya

Re: [doc] A better javadoc?

[Tim Ellison <t....@gmail.com>]

Alexey Varlamov wrote:
> 2008/2/12, Tim Ellison <t....@gmail.com>:
>> (Having a conversation with myself here :-)
>>
>> Take a look at
>>        http://www.jdocs.com/harmony/5.M5/overview-summary.html
>>
>> for the first attempt at generating our documentation for JDocs.
>> I uploaded the current HEAD, together with the corresponding source
>> code.  I called it M5 in anticipation but will refresh it and 'launch'
>> the doc site officially after we declare the milestone.
>>
>> Have a click around to see what you think.  Comments on the site
>> usability/behavior can be sent to the "jdocs-feedback" mail box at
>> dzone.com.  Comments on the quality of the javadoc comments can be
>> posted here!
>>
>> (Just beware that Sun source is also on the site, so check you are
>> looking at the right version.)
> 
> Yep, very actual warning - many links in docs are pointing to Sun JDK
> unexpectedly, it is quite easy to jump away from Harmony without ever
> noticing.

I'll our observations on to the JDocs guys.  I can fix it by making 
Harmony (and not OpenJDK) a favorite, then selecting search in favorites 
only -- but I agree it is misleading otherwise.

> BTW, no inheritance info for Harmony, is it just happened to be turned
> off in generation script?

Erm, not sure, I'll take a look.

Regards,
Tim

Re: [doc] A better javadoc?

[Alexey Varlamov <al...@gmail.com>]

2008/2/12, Tim Ellison <t....@gmail.com>:
> (Having a conversation with myself here :-)
>
> Take a look at
>        http://www.jdocs.com/harmony/5.M5/overview-summary.html
>
> for the first attempt at generating our documentation for JDocs.
> I uploaded the current HEAD, together with the corresponding source
> code.  I called it M5 in anticipation but will refresh it and 'launch'
> the doc site officially after we declare the milestone.
>
> Have a click around to see what you think.  Comments on the site
> usability/behavior can be sent to the "jdocs-feedback" mail box at
> dzone.com.  Comments on the quality of the javadoc comments can be
> posted here!
>
> (Just beware that Sun source is also on the site, so check you are
> looking at the right version.)

Yep, very actual warning - many links in docs are pointing to Sun JDK
unexpectedly, it is quite easy to jump away from Harmony without ever
noticing.
BTW, no inheritance info for Harmony, is it just happened to be turned
off in generation script?

Thanks,
Alexey

Re: [doc] A better javadoc?

[Tim Ellison <t....@gmail.com>]

(Having a conversation with myself here :-)

Take a look at
	http://www.jdocs.com/harmony/5.M5/overview-summary.html

for the first attempt at generating our documentation for JDocs.
I uploaded the current HEAD, together with the corresponding source 
code.  I called it M5 in anticipation but will refresh it and 'launch' 
the doc site officially after we declare the milestone.

Have a click around to see what you think.  Comments on the site 
usability/behavior can be sent to the "jdocs-feedback" mail box at 
dzone.com.  Comments on the quality of the javadoc comments can be 
posted here!

(Just beware that Sun source is also on the site, so check you are 
looking at the right version.)

Regards,
Tim

Tim Ellison wrote:
> Tim Ellison wrote:
>> Nadya Morozova wrote:
>>> I won't get your hopes too high, but if you really need this, I can play
>>> some tricks to make these docs more readable by:
>> <snip>
>>
>> I wouldn't say that we "really need this", but it seems a shame that 
>> we don't have any user-level code documentation linked from the website.
>>
>> Poking round a bit further, it seems that JDocs now has JavaSE 
>> documentation in quite a nice style.  I'll drop them a note to see if 
>> there is a way we can use their service for Harmony docs...
> 
> I have spoken to the guys at JDocs, and they are more than happy to host 
> our documentation -- which is very generous of them.
> 
> It simply means modifying our doc scripts to call their custom Ant task, 
> and uploading the results to their website.  The formatting etc. looks 
> really good, and there is a chance for people to provide feedback and 
> enhancements, so I think it is a great opportunity for us to showcase 
> the user-level doc (i.e. public/protected APIs).
> 
> Unless there is any objection I suggest we go ahead with this, and I'll 
> generate a test set of doc to upload.
> 
> As usual, patches and improvements to the javadoc comments are most 
> welcomed (send in via JIRA as ususal).
> 
> Regards,
> Tim
> 

Re: [doc] A better javadoc?

[Tim Ellison <t....@gmail.com>]

Tim Ellison wrote:
> Nadya Morozova wrote:
>> I won't get your hopes too high, but if you really need this, I can play
>> some tricks to make these docs more readable by:
> <snip>
> 
> I wouldn't say that we "really need this", but it seems a shame that we 
> don't have any user-level code documentation linked from the website.
> 
> Poking round a bit further, it seems that JDocs now has JavaSE 
> documentation in quite a nice style.  I'll drop them a note to see if 
> there is a way we can use their service for Harmony docs...

I have spoken to the guys at JDocs, and they are more than happy to host 
our documentation -- which is very generous of them.

It simply means modifying our doc scripts to call their custom Ant task, 
and uploading the results to their website.  The formatting etc. looks 
really good, and there is a chance for people to provide feedback and 
enhancements, so I think it is a great opportunity for us to showcase 
the user-level doc (i.e. public/protected APIs).

Unless there is any objection I suggest we go ahead with this, and I'll 
generate a test set of doc to upload.

As usual, patches and improvements to the javadoc comments are most 
welcomed (send in via JIRA as ususal).

Regards,
Tim

Re: [doc] A better javadoc?

[Tim Ellison <t....@gmail.com>]

Nadya Morozova wrote:
> I won't get your hopes too high, but if you really need this, I can play
> some tricks to make these docs more readable by:
<snip>

I wouldn't say that we "really need this", but it seems a shame that we 
don't have any user-level code documentation linked from the website.

Poking round a bit further, it seems that JDocs now has JavaSE 
documentation in quite a nice style.  I'll drop them a note to see if 
there is a way we can use their service for Harmony docs...

Regards,
Tim