Bugs item #1015389, was opened at 2004-08-24 16:43
Message generated for change (Comment added) made by colinguthrie
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: Colin Guthrie (colinguthrie)
Date: 2004-09-22 13:07
Message:
Logged In: YES
user_id=1122390
That's better!!!
Thanks Kurt. I also appreciate what you say RE the
whitespace and agree with you 100% now that I appreciate how
things are glued together currently.
Right, I'm gonna do what we at my work call "do a Richard"
which is basically point out trivial changes that would
improve things marginally!! (we had a really annoying person
called richard work for us once!!)
Anyways. On the main noNamespace page, there is an Element
Summary which show the first sentance of the doc. for that
element. There is also a Complex Element Summary which shows
the same.
If we now jump to the Nested Element Summary. It does not
show the first line of the documentation, like the other,
and I think personally that it should.
This is probably a matter of changing some stuff in an XLT
somewhere judging by your past comments, but despite my
needing to document XML Schemas, my knowledge of transforms
and such is pretty much non existant which is why I've not
attached a patch.... sorry!!
Anyways, thanks for the development you've done. It's a very
useful tool!
All the best
Col.
----------------------------------------------------------------------
Comment By: Kurt Riede (kriede)
Date: 2004-09-20 19: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 19: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 10: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 10: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 09: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 16: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-03 22: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
|
