Alexandro,
you may want to look into
<http://www.ooocon.org/index.php/ooocon/2010/paper/view/196>, once the
slides are made available online by Peter (he has been doing a lot of
work and needs probably more time to process all of the slides of the
numerous presentations at this year's OOoCon, all in all, an incredible
time-consuming task).
"UNO API Info" is a tool that allows to gain documentation on the fly
from any OOo programming language by either supplying the name of an IDL
type (the fully qualified name e.g. of a service, an interface, a
constant group, etc.) or by supplying any UNO object which then gets
documented using reflection (which programmatically can be very
challenging as you write yourself).
The result is a writer/pdf document that has all the information
formatted in a nice manner (members sorted by name, members sorted by
type and name, constants sorted by name, depicting their values,
properties sorted by name giving their type and attributes like
maybevoid and the like, etc.) and also linked directly to the OOo
documentation on the web. This way one can get an overview of all the
functionality that is available, and for further documentation you just
follow the links of those types/members that you are interested in.
Finally, one can also have not only a single IDL service, interface or
single UNO object documented, but also the members they contain ("layer:
2").
If you point your browser to
<http://wi.wu.ac.at/rgf/rexx/misc/OOoCon/2010_Budapest/>, then you'll
get to see example PDFs that got generated on the fly by supplying the
UNO object representing a writer object (which interestingly implements
more than one service). This is a somewhat extreme example, which also
demonstrates how much functionality is at the hands of a programmer of
the writer component. However, it also demonstrates how documentation
can be devised that lets one see the forest (instead of the many trees
making up the forest) too.
At this OOoCon I also presented this live, demonstrating how to use this
facility among other languages from JavaScript and Python.
There is a readme/documentation of the tool at
<http://wi.wu.ac.at/rgf/rexx/misc/OOoCon/2010_Budapest/read-me-UNO_API_info.html.pdf>,
which documents this utility (including code to demonstrate how to use
it from Basic, Java, ooRexx as well).
The tool is not meant as a replacement for XRay and relatives, but as an
additional means of on-the-fly-documentation generation with overview
character to help the programmers mastering their challenging work.
If you (or anyone else) have (has) any questions/comments regarding this
tool, then please just post them via this list.
HTH,
---rony
On 10.09.2010 16:19, Alexandro Colorado wrote:
> 2010/9/6 Jürgen Schmidt <juergen.schm...@oracle.com>
>
>
>> Hi Alexandro,
>>
>> thanks for picking up this topic immediately.
>>
>> Whatever we think will be an appropriate solution to provide an easier way
>> how users can give feedback. I would suggest that we create a tool that use
>> the input from the IDLs (the generated type library) as input and produce
>> based on this info whatever is necessary.
>>
>>
> Do we have this tool already? How does the current documentation gets form?
> AFAIK the UNO interface is atomic and this will provide far too many items.
>
>
>
>> Follow up please only on one list -> dev@api.openoffice.org
>>
>> Juergen
>>
>>
>>
>> On 9/5/10 10:37 AM, Alexandro Colorado wrote:
>>
>>
>>> Hi during OOoCon a conversation started about the lack of examples on the
>>> API documentation as far as contributions goes. Basically there are
>>> several
>>> places where to go to:
>>> - API Documentation
>>> - CodeSnippets
>>> - Developer Guide
>>> - OOo Wiki
>>>
>>> The main issue is that users and readers have low accessibility to
>>> introduce
>>> examples or comments on the documentation. There have been some possible
>>> solutions discussed:
>>> - Move the API Docs to the Wiki
>>> - Version the API Docs depending on the OOo version
>>> - Close codeSnippets or move it to a technology that allow users to just
>>> paste snippets directly on the site
>>>
>>> As always the issue becomes lack of resources, time and information. My
>>> feeling is that if we air this topic with possible solutions would help us
>>> find better solutions. I do have a small script that allow me to clean off
>>> the documentation from the collabnet HTML and just isolate the HTML
>>> snippet.
>>> My next step could be to find a converter from HTML to a wikilang that
>>> allow
>>> us to easy publish it on the wiki and publish it on the wiki as a service
>>> (batch upload).
>>>
>>> Help is welcomed.
>>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org
For additional commands, e-mail: dev-h...@api.openoffice.org
