[ xframe-Bugs-1015389 ] documentation of nested element incomplete

Bugs item #1015389, was opened at 2004-08-24 18:43
Message generated for change (Comment added) made by kriede
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=454391&aid=1015389&group_id=48863

Category: all platforms
Group: xsddoc-0.5-beta
Status: Open
Resolution: None
Priority: 5
Submitted By: Kurt Riede (kriede)
Assigned to: Kurt Riede (kriede)
Summary: documentation of nested element incomplete

Initial Comment:
When declaring nested elements in a russion-doll design, 
the nested elements are not listed in the namespace-
overview and the namespace-summary. Furthermore the 
documentation of attributes of nested tags is missing.

In an easy solution, they might be listed in the 
namespace-overview like this:

russianDoll
russianDoll.rdRoot
russianDoll.rdRoot.rdChild1
russianDoll.rdRoot.rdChild2

As a minimum, the links could direct to the 
documentation of the main element.

But simmilar to JavaDoc, it would be more helpfull to 
have a seperate documentation pages for each inner 
declaration. Otherwise it would be quiet complex to 
display and to understand, which attribute is used where.

----------------------------------------------------------------------

>Comment By: Kurt Riede (kriede)
Date: 2004-09-20 21:36

Message:
Logged In: YES 
user_id=484961

Hi again,

the solution for the unwanted repeated documentation was 
quite easy to do in component.xsl
Now available in CVS HEAD.

Concerning the white-spaces:
There are millions of ways to handle this... As discussed 
earlier, we think the current solution fits many cases. 
Furthermore we will allow to define an external XSLT file to do 
the final formatting instead of xml2html.xsl, so everybody can 
choose the prefered way to handle white space or anything 
else.

Regards
Kurt

----------------------------------------------------------------------

Comment By: Kurt Riede (kriede)
Date: 2004-09-20 21:06

Message:
Logged In: YES 
user_id=484961

Hi Colin,

your example is now integrated into the stress test.
Now I understand what you mean:
In a schema, each tag can have an 
annotation/documentation child, so it is good to collect all 
documentation tags recursivle as xsddoc does (and as 
described in the XML-Schema Infoset).
But as soon as we come to a nested type declaraion, xsddoc 
should stop recursion, otherwise the documentation is getting 
out of scope and duplicated.
I'll change that soon.

Regarding the formatting of the documentation (Newlines, ...) 
please also read the feature request"documentation elements 
should not be in pre environment":
https://sf.net/tracker/index.php?
func=detail&aid=853750&group_id=48863&atid=454394

Thanx for your comments.

Regards
Kurt

----------------------------------------------------------------------

Comment By: Colin Guthrie (colinguthrie)
Date: 2004-09-20 12:11

Message:
Logged In: YES 
user_id=1122390

Apologies:

View the index page, click noNamespace, click complextypeType.

should read

View the index page, click noNamespace, click dummytypeType
(under Complex Type Summary)

You'll also notice from my file layout that the tabs in my
files seem to follow through to the final documentation. Is
there a way to ignore the line start/end whitespace??
Newlines are important for me tho'. I guess some folks would
like to draw ascii art type stuff so this may not be a great
idea for everyone...

----------------------------------------------------------------------

Comment By: Colin Guthrie (colinguthrie)
Date: 2004-09-20 12:07

Message:
Logged In: YES 
user_id=1122390

I've played with this a bit, and the problem I mentioned
does seem to be solved now, but I have one comment about
where the documentation is listed.

Many of the annotations/documentation I put in a type are
only relevent in the context of the element they are
contained within.

It would appear that the CVS head version places this
documentation in two places. Once inside the element where I
want it, but also on the over page.

I've created a schema for testing here:
http://www.csuk-solutions.net/opensource/test/xsddoc.xsd.
Once you generate docs, (xsddoc -t "XML Schema for Test" -o
test -verbose xsddoc.xsd), View the index page, click
noNamespace, click complextypeType. You will see that the
documentation for the element "name" also appears under the
documentation for the encapsulating element, which means the
documentation is out of context.

Hope this feedback helps.

Col.

----------------------------------------------------------------------

Comment By: Kurt Riede (kriede)
Date: 2004-09-20 11:21

Message:
Logged In: YES 
user_id=484961

Hi Colin,

the problem seems to be solved.
Could you please retest with current CVS HEAD?

Regards
Kurt


----------------------------------------------------------------------

Comment By: Colin Guthrie (colinguthrie)
Date: 2004-09-15 18:11

Message:
Logged In: YES 
user_id=1122390

This seems to work OK for me. Now (very) happily seeing my
nested element documented.

I do get this warning when I start xsddoc:
fatal: :819:82 A node test that matches either NCName:* or
QName was expected.
fatal: :819:82 Extra illegal tokens: 'name', '(', '..', ')',
'=', ''xs:redefine'', ']'

But the error does not actually seem to be fatal after all
as the docs /do/ get generated.

This may be due to some other random CVS related thing or
just my build....

Thanks for developing this tool tho', it's much appreciated.
I like the docs made by XMLSpy but seeing as it doesn't run
on Linux and it costs loads, I can't really use it.

----------------------------------------------------------------------

Comment By: Kurt Riede (kriede)
Date: 2004-09-04 00:30

Message:
Logged In: YES 
user_id=484961

A first good solution is now available in CVS HEAD.
We are now awaiting feedbach from users before we release a 
new version of xsddoc.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=454391&aid=1015389&group_id=48863


-------------------------------------------------------
This SF.Net email is sponsored by: YOU BE THE JUDGE. Be one of 170
Project Admins to receive an Apple iPod Mini FREE for your judgement on
who ports your project to Linux PPC the best. Sponsored by IBM.
Deadline: Sept. 24. Go here: http://sf.net/ppc_contest.php