32582 - xpidl doc backend needed

Status: RESOLVED WONTFIX

(Core :: XPCOM, defect, P5)

Description

[Mike McCabe]

We need a documentation-generating backend for xpidl.

Some preliminary work is checked into the tree.  It generates a simple HTML file
that lists some aspects of the processed interfaces.  It's still a ways from a
finished product, though.

Comment 1

[Mike McCabe]

Added 'helpwanted' to keyword field.  This project is an excellent candidate for
an outside developer.  It's potentially high-profile, it's self-contained
(doesn't require much knowledge of or depend too much on Mozilla architecture)
and could also be useful to other open-source projects that use IDL files, such
as GNOME.

Comment 2

[Brian Smith (:briansmith, :bsmith, use NEEDINFO?)]

What format do you want the documentation in? I've just started an IDL->XMI 
documentation generator and I could stop working on "pure CORBA IDL" and focus 
on XPIDL. I think that XMI would be good because:

* This bug can be resolved by me iif XMI is used, since i'm doing IDl->XMI 
anyway for a seperate project.
* XMI holds a lot of information and is easily searchable, useful for QA-
related queries. For example, you could do queries "which methods have a 
parameter of type 'string', which ones are using '[shared]'", "what interfaces 
are inherited from this one", etc. In HTML, you lose most of the information 
about such relationships.

* It might make things easier to find and fix if decisions such as "make all 
|string| paraemters |wstring| in scriptable interfaces" or "convert all 
|wstring| methods to use (data, length) pairs" are made (as I hope they are).

* XMI is XML, and Mozilla can understand XML. With a CSS stylesheet, Mozilla 
could display the XMI documentation as a web page. XMI is also somewhat easy to 
translate to HTML (e.g. using a XSLT processor) and provides for instant UML 
diagrams, etc, etc.

Comment 3

[Mike McCabe]

Sounds great!

We're not at all wed to HTML.  What we need is exactly what you describe - a
browsable collection of information about our interfaces, both for documentation
and to allow us to review what we're doing at a high level.  We'd like to
present this in a browsable format on mozilla.org.  Beyond these basic needs,
the project is wide open.  XMI sounds like it will fit the bill - whatever you
can do would be greatly appreciated.  As we've based our IDL on that of the
GNOME project, it's likely that work in this area will be useful for other open
source projects as well.

Let me know how I can help.

Comment 4

[Mike McCabe]

[SPAM] Marking milestone 'future' as part of nsbeta3 triage.

Comment 5

[Phil Schwartau]

Mass-reassigning mccabe's non-JS, non-Rhino bugs to jband (34 total). 

Would like to cc mccabe; but the mass-reassign page does not allow this. 
I'll leave it up to mccabe to decide if he wants to be cc'ed on these - 

Comment 6

[John Bandhauer]

mass reassign of xpidl bugs to [e-mail]

Comment 7

[David Bradley]

Do we really need this? Aren't there other tools that will do the job better,
such as Doxygen?

Comment 8

[Braden]

I don't think this is needed. If there were sufficient demand for it, 
certainly the functionality would have been filled out by now. It stands to 
reason that the role of documentation generation is sufficiently filled by 
doxygen and similar tools. Filed bug 243849.

Comment 9

[David Bradley]

I agree with the final comment. And I think we need to remove the dead weight,
Bug 243849