After reading the source-code for the reference build tools, here's my
result: Everything is working as expected!
Without a doc-comment on either <library> or <class>,
<dataselectionmanager> is not placed into a 'topic' and topics are
required otherwise there is no doc-book entry.
Short intro for js2doc:
A lzx-file is transformed into:
---
<unit path="" id="" unitid="" (access="" topic="" subtopic="")?>
(<doc>...</doc>)?
</unit>
---
And a <class> is transformed into:
---
<property name="" id="" unitid="" (access="" topic="" subtopic="")?>
(<doc>...</doc>)?
<class>...</class>
</property>
---
The access, topic and subtopic attributes are filled from the <!--- -->
doc-comments and also inherited from the parent <unit> elements, see
org/openlaszlo/js2doc/ReprocessComments.java.
(The parent <unit> for an element x can be retrieved through the @unitid
attribute.)
How are doc-comments assigned to elements?
See the "processcomment" <template> in docs/src/xsl/lzx2js2doc.xsl, the
preceding comment for an element is defined by this xpath:
preceding-sibling::node()[not(self::text()[not(normalize-space())])][1][self::comment()]
Finally the "reference.dbk.build" target in docs/src/build.xml is
responsible for generating the doc-books for every topic, cf. the
<antcall target="dbk.topic.generate"> calls with the "filter.topic"
<param>.
Let's put all things together:
<class name="dataselectionmanager"> is visited, js2doc <property> is
written. Is there a preceding comment on <class>? No, the first node
which is not whitespace-only text-node is the <include> element.
ReprocessComments will now try to infer the topic for the <property> by
visiting the parent <unit>s. First parent <unit> is
dataselectionmanager.lzx: no doc-comment on the <library> -> no topic
found at this step. dataselectionmanager.lzx's parent <unit> is
components/util/library.lzx, but still no doc-comment.
components/util/library.lzx parent <unit> is components/library.lzx, but
again no doc-comment and hence no topic in total. That means the
<property> for <class name="dataselectionmanager"> looks like:
<property id="lz.dataselectionmanager" name="lz.dataselectionmanager"
unitid="lps.components.utils.dataselectionmanager.lzx">
And as described above, the topic attribute is mandatory to generate the
doc-book entry, but as demonstrated dataselectionmanager's <property>
did not get that attribute assigned.
You can verify this by inspecting the intermediate files from the
reference build process, components{-raw}.xml and
doctestLaszloLibrary-{*}.js2doc. Or by altering the build.xml to
generated dbk-files for entries without a topic:
In <target name="reference.dbk.build">:
<antcall target="dbk.topic.generate" inheritAll="true">
<param name="local.input.file" value="${ref.file.in}"/>
<param name="local.output.file"
value="${reference.build.dir}/noneref.dbk"/>
<param name="filter.topic" value="none"/>
<param name="visibility.filter" value="${ref.visibility.filter}"/>
<param name="dbk.show.comments" value="${ref.show.comments}"/>
<param name="dbk.show.fixmes" value="${ref.show.fixmes}"/>
</antcall>
Now you'll an additional "noneref.dbk" file in docs/src/build/reference,
open that file and you'll see the missing dataselectionmanager entry!
(Before you actually can generate the "none" topic dbk-file, you must
fix a bug in js2doc2dbk.xsl, remove the `<xsl:if test="count(decls) >
0">` line in `<xsl:template match="js2doc" mode="decls-no-topic">`.)
So I'd propose to add an additional step to the reference build process
to verify all <property>s have got a topic attribute. And if there are
any <property>s without a topic, a useful warning should be emitted.
On 10/30/2010 7:16 PM, P T Withington wrote:
You're mostly right, as you will see from my subsequent change...
where I just moved the doc-comment out of the library, and now everything
works. Yes, I am too lazy to wait for my personal machine to do the doc build,
so I tested with the build machine, which is not the nicest thing to do. Now I
have drunk all the coffee I can take for the day, and this solution builds on
my personal machine, so I am trying once more on the build machine. Fingers
crossed. :)
What's with the doc-comment? It seems to make the doc generator only take the
next XML tag and ignore everything else?
On 2010-10-30, at 13:03, André Bargull wrote:
Not approved!
I'd do the following steps:
- delete dataselectioninclude.lzx
- rebuild lzx-autoincludes.properties, don't add any hand-crafted entries
- open dataselectionmanager.lzx
-- remove the comment about "we cannot directly include ..."
-- add<include href="selectionmanager.lzx"/> at the top (!), directly after
the<library> start-tag
-- remove any blank lines between the<!--- --> doc-comment and<class>
[-- add "@lzxname dataselectionmanager" between @subtopic and @devnote] (maybe
this step is not necessary...)
- rebuild the reference on your local machine
- go and drink some coffee
- come back to the computer
- go and drink more coffee
- come back again and see everything went fine
I think the issue was only caused by the<include> after the<!--- -->
doc-comment.
(Hmm, hopefully it's going to work for you, too. Otherwise this will turn out to be a bit
embarrassing for me, maybe I shouldn't have yelled so loud "Not approved!" :-) )
On 10/30/2010 1:21 PM, P T Withington wrote:
Change ptw-20101030-exq by [email protected] on 2010-10-30 06:59:08 EDT
in /Users/ptw/OpenLaszlo/trunk-3
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Get nightly builds working again
Bugs Fixed: LPP-9475 4.7-based tree fails to compile in 4.9 with no useful
error message
Technical Reviewer: [email protected] (pending)
QA Reviewer: antun (pending)
Details:
Revert to work-around introduced in LPP-9180
Tests:
kicking off a nightly build
Files:
M WEB-INF/lps/misc/lzx-autoincludes.properties
M lps/components/utils/dataselectioninclude.lzx
M lps/components/utils/dataselectionmanager.lzx
Changeset: http://svn.openlaszlo.org/openlaszlo/patches/ptw-20101030-exq.tar
