You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@qpid.apache.org by Jonathan Robie <jo...@redhat.com> on 2008/12/10 16:49:06 UTC
Size of doxygen API documentation
Someone asked me why the API documentation is so large. About 27 Meg is
due to the HTML files, I am not aware of anything we can do to make that
part smaller.
$ du -bc *html | grep total
27,031,097 total
The .md5 and .map files are used to optimize regeneration, they do not
need to be shipped with the documentation.
$ du -bc *md5 | grep total
34,976 total
$ du -bc *map | grep total
1,456,027 total
But the bulk of the size is due to the .png files:
$ du -bc *png | grep total
150,298,506 total
You can get rid of 2/3 this by setting HAVE_DOT in user.doxygen to "NO"
if you don't want the class, collaboration, and group graphs:
# If you set the HAVE_DOT tag to YES then doxygen will assume the
dot tool is
# available from the path. This tool is part of Graphviz, a graph
visualization
# toolkit from AT&T and Lucent Bell Labs. The other options in this
section
# have no effect if this option is set to NO (the default)
HAVE_DOT = NO
But it's still large:
$ du -bc *png | grep total
437,850 total
Is the extra size worth it for these graphs? It's still pretty big even
without them.
Jonathan
Re: Size of doxygen API documentation
Posted by Carl Trieloff <cc...@redhat.com>.
Jonathan Robie wrote:
> Alan Conway wrote:
>> On Wed, 2008-12-10 at 11:54 -0500, Hiram Chirino wrote:
>>
>>> Is the entire API of interest to the end user? Perhaps only the
>>> interesting parts need doxygen applied.
>>>
>>
>> The interesting parts are (supposed to be) marked with
>> \ingroup clientapi
>> Its probably not applied to every file where its needed (e.g. some of
>> the framing files) but we definitely should be restricting the
>> documented API to the classes that we actually want users to play with.
>>
>
> The problem is that many of these methods have parameters or returns
> that belong to the part of the API you say you don't want to expose,
> but people need these types to use the ones you say you do want to
> expose. That's why I brought in framing, for instance.
>
> How do we identify the API we want to expose?
>
> How do we ensure it is orthogonal to the classes used to implement it?
>
I would leave the doc verbose for now. if needed, put it in a separate tar.
Carl.
Re: Size of doxygen API documentation
Posted by Jonathan Robie <jo...@redhat.com>.
Alan Conway wrote:
> On Wed, 2008-12-10 at 11:54 -0500, Hiram Chirino wrote:
>
>> Is the entire API of interest to the end user? Perhaps only the
>> interesting parts need doxygen applied.
>>
>
> The interesting parts are (supposed to be) marked with
> \ingroup clientapi
> Its probably not applied to every file where its needed (e.g. some of
> the framing files) but we definitely should be restricting the
> documented API to the classes that we actually want users to play with.
>
The problem is that many of these methods have parameters or returns
that belong to the part of the API you say you don't want to expose, but
people need these types to use the ones you say you do want to expose.
That's why I brought in framing, for instance.
How do we identify the API we want to expose?
How do we ensure it is orthogonal to the classes used to implement it?
Jonathan
Re: Size of doxygen API documentation
Posted by Alan Conway <ac...@redhat.com>.
On Wed, 2008-12-10 at 11:54 -0500, Hiram Chirino wrote:
> Is the entire API of interest to the end user? Perhaps only the
> interesting parts need doxygen applied.
The interesting parts are (supposed to be) marked with
\ingroup clientapi
Its probably not applied to every file where its needed (e.g. some of
the framing files) but we definitely should be restricting the
documented API to the classes that we actually want users to play with.
Re: Size of doxygen API documentation
Posted by Hiram Chirino <hi...@hiramchirino.com>.
Is the entire API of interest to the end user? Perhaps only the
interesting parts need doxygen applied.
On Wed, Dec 10, 2008 at 10:49 AM, Jonathan Robie
<jo...@redhat.com> wrote:
> Someone asked me why the API documentation is so large. About 27 Meg is due
> to the HTML files, I am not aware of anything we can do to make that part
> smaller.
>
> $ du -bc *html | grep total
> 27,031,097 total
>
> The .md5 and .map files are used to optimize regeneration, they do not need
> to be shipped with the documentation.
>
> $ du -bc *md5 | grep total
> 34,976 total
> $ du -bc *map | grep total
> 1,456,027 total
>
> But the bulk of the size is due to the .png files:
>
> $ du -bc *png | grep total
> 150,298,506 total
>
> You can get rid of 2/3 this by setting HAVE_DOT in user.doxygen to "NO" if
> you don't want the class, collaboration, and group graphs:
>
> # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool
> is
> # available from the path. This tool is part of Graphviz, a graph
> visualization
> # toolkit from AT&T and Lucent Bell Labs. The other options in this
> section
> # have no effect if this option is set to NO (the default)
>
> HAVE_DOT = NO
>
> But it's still large:
>
> $ du -bc *png | grep total
> 437,850 total
>
> Is the extra size worth it for these graphs? It's still pretty big even
> without them.
>
> Jonathan
>
--
Regards,
Hiram
Blog: http://hiramchirino.com
Open Source SOA
http://open.iona.com