[3/9] doc: preserve links produced by Doxygen

Submitted by Bill Spitzak on Nov. 12, 2014, 2:42 a.m.

Details

Message ID 1415760182-19568-4-git-send-email-spitzak@gmail.com
State Accepted
Headers show

Not browsing as part of any series.

Commit Message

Bill Spitzak Nov. 12, 2014, 2:42 a.m.
These links are pretty useful for navigation, though sometimes excessive
(you can turn them off by putting % before the word in the comment).

I had to turn off validation because it failed on missing and duplicate
target id's, which this produces.
---
 doc/publican/Makefile.am             |    1 +
 doc/publican/doxygen-to-publican.xsl |   23 ++++++++---------------
 2 files changed, 9 insertions(+), 15 deletions(-)

Patch hide | download patch | download mbox

diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am
index b30a471..9fc4e0b 100644
--- a/doc/publican/Makefile.am
+++ b/doc/publican/Makefile.am
@@ -47,6 +47,7 @@  if HAVE_XMLTO
 if HAVE_XSLTPROC
 noinst_DATA = Wayland $(publican_targets)
 XMLTO_PARAM = \
+	--skip-validation \
 	--stringparam chunk.section.depth=0 \
 	--stringparam toc.section.depth=1 \
 	--stringparam html.stylesheet=css/default.css
diff --git a/doc/publican/doxygen-to-publican.xsl b/doc/publican/doxygen-to-publican.xsl
index 99193e1..7f7abe9 100644
--- a/doc/publican/doxygen-to-publican.xsl
+++ b/doc/publican/doxygen-to-publican.xsl
@@ -61,7 +61,7 @@ 
 </xsl:template>
 
 <xsl:template match="ref">
-  <emphasis><xsl:apply-templates /></emphasis>
+  <link linkend="{@refid}"><xsl:value-of select="." /></link>
 </xsl:template>
 
 <xsl:template match="simplesect[@kind='return']">
@@ -81,10 +81,7 @@ 
   <itemizedlist>
     <listitem>
       <para>
-        See also:
-        <xsl:for-each select="para/ref">
-          <emphasis><xsl:apply-templates /><xsl:text> </xsl:text></emphasis>
-        </xsl:for-each>
+        See also: <xsl:apply-templates />
       </para>
     </listitem>
   </itemizedlist>
@@ -94,7 +91,7 @@ 
   <itemizedlist>
     <listitem>
       <para>
-        Since: <xsl:apply-templates select="para"/>
+        Since: <xsl:apply-templates />
       </para>
     </listitem>
   </itemizedlist>
@@ -104,10 +101,6 @@ 
   <emphasis>Note: <xsl:apply-templates /></emphasis>
 </xsl:template>
 
-<xsl:template match="programlisting//sp">
-  <xsl:text> </xsl:text>
-</xsl:template>
-
 <xsl:template match="sp">
   <xsl:text> </xsl:text>
 </xsl:template>
@@ -135,9 +128,9 @@ 
 <!-- methods -->
 <xsl:template match="memberdef" >
   <xsl:if test="@kind = 'function' and @static = 'no'">
-    <varlistentry>
+    <varlistentry id="{@id}">
         <term>
-          <xsl:apply-templates select="name"/>
+          <xsl:value-of select="name"/>
         - <xsl:apply-templates select="briefdescription" />
         </term>
         <listitem>
@@ -154,8 +147,8 @@ 
 
 <!-- classes -->
 <xsl:template match="compounddef" >
-    <xsl:if test="@kind = 'class' ">
-    <varlistentry>
+    <xsl:if test="@kind = 'class'">
+    <varlistentry id="{@id}">
         <term>
             <xsl:apply-templates select="compoundname" />
             <xsl:if test="briefdescription">
@@ -164,7 +157,7 @@ 
         </term>
 
         <listitem>
-          <xsl:apply-templates select="detaileddescription/para" />
+          <xsl:apply-templates select="detaileddescription" />
         </listitem>
     </varlistentry>
     </xsl:if>

Comments

On Tue, 11 Nov 2014 18:42:56 -0800
Bill Spitzak <spitzak@gmail.com> wrote:

> These links are pretty useful for navigation, though sometimes excessive
> (you can turn them off by putting % before the word in the comment).
> 
> I had to turn off validation because it failed on missing and duplicate
> target id's, which this produces.

Yeah, very useful. Do we have a plan how to get validation back and
working? I assume it's not useless.


Thanks,
pq


> ---
>  doc/publican/Makefile.am             |    1 +
>  doc/publican/doxygen-to-publican.xsl |   23 ++++++++---------------
>  2 files changed, 9 insertions(+), 15 deletions(-)
> 
> diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am
> index b30a471..9fc4e0b 100644
> --- a/doc/publican/Makefile.am
> +++ b/doc/publican/Makefile.am
> @@ -47,6 +47,7 @@ if HAVE_XMLTO
>  if HAVE_XSLTPROC
>  noinst_DATA = Wayland $(publican_targets)
>  XMLTO_PARAM = \
> +	--skip-validation \
>  	--stringparam chunk.section.depth=0 \
>  	--stringparam toc.section.depth=1 \
>  	--stringparam html.stylesheet=css/default.css
> diff --git a/doc/publican/doxygen-to-publican.xsl b/doc/publican/doxygen-to-publican.xsl
> index 99193e1..7f7abe9 100644
> --- a/doc/publican/doxygen-to-publican.xsl
> +++ b/doc/publican/doxygen-to-publican.xsl
> @@ -61,7 +61,7 @@
>  </xsl:template>
>  
>  <xsl:template match="ref">
> -  <emphasis><xsl:apply-templates /></emphasis>
> +  <link linkend="{@refid}"><xsl:value-of select="." /></link>
>  </xsl:template>
>  
>  <xsl:template match="simplesect[@kind='return']">
> @@ -81,10 +81,7 @@
>    <itemizedlist>
>      <listitem>
>        <para>
> -        See also:
> -        <xsl:for-each select="para/ref">
> -          <emphasis><xsl:apply-templates /><xsl:text> </xsl:text></emphasis>
> -        </xsl:for-each>
> +        See also: <xsl:apply-templates />
>        </para>
>      </listitem>
>    </itemizedlist>
> @@ -94,7 +91,7 @@
>    <itemizedlist>
>      <listitem>
>        <para>
> -        Since: <xsl:apply-templates select="para"/>
> +        Since: <xsl:apply-templates />
>        </para>
>      </listitem>
>    </itemizedlist>
> @@ -104,10 +101,6 @@
>    <emphasis>Note: <xsl:apply-templates /></emphasis>
>  </xsl:template>
>  
> -<xsl:template match="programlisting//sp">
> -  <xsl:text> </xsl:text>
> -</xsl:template>
> -
>  <xsl:template match="sp">
>    <xsl:text> </xsl:text>
>  </xsl:template>
> @@ -135,9 +128,9 @@
>  <!-- methods -->
>  <xsl:template match="memberdef" >
>    <xsl:if test="@kind = 'function' and @static = 'no'">
> -    <varlistentry>
> +    <varlistentry id="{@id}">
>          <term>
> -          <xsl:apply-templates select="name"/>
> +          <xsl:value-of select="name"/>
>          - <xsl:apply-templates select="briefdescription" />
>          </term>
>          <listitem>
> @@ -154,8 +147,8 @@
>  
>  <!-- classes -->
>  <xsl:template match="compounddef" >
> -    <xsl:if test="@kind = 'class' ">
> -    <varlistentry>
> +    <xsl:if test="@kind = 'class'">
> +    <varlistentry id="{@id}">
>          <term>
>              <xsl:apply-templates select="compoundname" />
>              <xsl:if test="briefdescription">
> @@ -164,7 +157,7 @@
>          </term>
>  
>          <listitem>
> -          <xsl:apply-templates select="detaileddescription/para" />
> +          <xsl:apply-templates select="detaileddescription" />
>          </listitem>
>      </varlistentry>
>      </xsl:if>
On 11/25/2014 06:46 AM, Pekka Paalanen wrote:
> On Tue, 11 Nov 2014 18:42:56 -0800
> Bill Spitzak <spitzak@gmail.com> wrote:
>
>> These links are pretty useful for navigation, though sometimes excessive
>> (you can turn them off by putting % before the word in the comment).
>>
>> I had to turn off validation because it failed on missing and duplicate
>> target id's, which this produces.
>
> Yeah, very useful. Do we have a plan how to get validation back and
> working? I assume it's not useless.

Is there any way to make it ignore links to missing and duplicate 
targets but validate everything else?

Also I suppose a much more complex xslt script would do this by actually 
building data structures and producing only the used tags.

My knowledge of xslt consists of asking questions on google and looking 
at the existing xslt scripts.
On Tue, 25 Nov 2014 09:44:02 -0800
Bill Spitzak <spitzak@gmail.com> wrote:

> On 11/25/2014 06:46 AM, Pekka Paalanen wrote:
> > On Tue, 11 Nov 2014 18:42:56 -0800
> > Bill Spitzak <spitzak@gmail.com> wrote:
> >
> >> These links are pretty useful for navigation, though sometimes excessive
> >> (you can turn them off by putting % before the word in the comment).
> >>
> >> I had to turn off validation because it failed on missing and duplicate
> >> target id's, which this produces.
> >
> > Yeah, very useful. Do we have a plan how to get validation back and
> > working? I assume it's not useless.
> 
> Is there any way to make it ignore links to missing and duplicate 
> targets but validate everything else?
> 
> Also I suppose a much more complex xslt script would do this by actually 
> building data structures and producing only the used tags.
> 
> My knowledge of xslt consists of asking questions on google and looking 
> at the existing xslt scripts.
> 

I'd be interested in hearing how we end up with
a) missing targets, and b) duplicate targets.

Could missing targets be fixed by documenting things that are not yet
documented? If yes, that would probably be nice.

If we ever get duplicate targets, then obviously some links point to
wrong things, because they cannot differentiate between the two
different targets of the same id. Is there something we could do in the
actual documentation to fix these? E.g. do we accidentally have two
different documentation blocks for a same thing, and merging them
would fix it?

Or are duplicates perhaps due to us having, say, struct wl_display a
different thing on server vs. client?

I'm adding Jon to CC, since he seems interested in things XML and docs.


Thanks,
pq
On 11/25/2014 11:52 PM, Pekka Paalanen wrote:
> I'd be interested in hearing how we end up with
> a) missing targets, and b) duplicate targets.
> 
> Could missing targets be fixed by documenting things that are not yet
> documented? If yes, that would probably be nice.
> 
> If we ever get duplicate targets, then obviously some links point to
> wrong things, because they cannot differentiate between the two
> different targets of the same id. Is there something we could do in the
> actual documentation to fix these? E.g. do we accidentally have two
> different documentation blocks for a same thing, and merging them
> would fix it?
> 
> Or are duplicates perhaps due to us having, say, struct wl_display a
> different thing on server vs. client?
> 
> I'm adding Jon to CC, since he seems interested in things XML and docs.

Definitely sounds like something I can track down and address (since I'm
experienced with xslt, doxygen, etc). At the very least I should be able
to spot the worst blockers.

One step might be to get anything that is truly undocumented replaced
with doxygen todo tags so we get a build without warnings but can still
get a list of items to fix fully at some later time.
On Wed, 26 Nov 2014 00:38:20 -0800
"Jon A. Cruz" <jonc@osg.samsung.com> wrote:

> On 11/25/2014 11:52 PM, Pekka Paalanen wrote:
> > I'd be interested in hearing how we end up with
> > a) missing targets, and b) duplicate targets.
> > 
> > Could missing targets be fixed by documenting things that are not yet
> > documented? If yes, that would probably be nice.
> > 
> > If we ever get duplicate targets, then obviously some links point to
> > wrong things, because they cannot differentiate between the two
> > different targets of the same id. Is there something we could do in the
> > actual documentation to fix these? E.g. do we accidentally have two
> > different documentation blocks for a same thing, and merging them
> > would fix it?
> > 
> > Or are duplicates perhaps due to us having, say, struct wl_display a
> > different thing on server vs. client?
> > 
> > I'm adding Jon to CC, since he seems interested in things XML and docs.
> 
> Definitely sounds like something I can track down and address (since I'm
> experienced with xslt, doxygen, etc). At the very least I should be able
> to spot the worst blockers.
> 
> One step might be to get anything that is truly undocumented replaced
> with doxygen todo tags so we get a build without warnings but can still
> get a list of items to fix fully at some later time.

Sounds good, when they are required for getting rid of
--skip-validation.

I'm not fond of the idea of doing that for all of the Doxygen warnings
about missing documentation just because it prints a warning during the
build. Seeing those warning irritate (at least me) every time you see
them, so that's some motivation to document things. I wouldn't want to
take that motivation away. :-)

If you get a list of things, where adding documentation would help for
removing --skip-validation, maybe I could write some.


Thanks,
pq
On 11/25/2014 11:52 PM, Pekka Paalanen wrote:

> I'd be interested in hearing how we end up with
> a) missing targets, and b) duplicate targets.
>
> Could missing targets be fixed by documenting things that are not yet
> documented? If yes, that would probably be nice.

The missing targets are from portions of the doxygen output that is not 
copied to the final result, especially because only "classes" are copied 
and not other structures, but I think there was some other output that 
would require even more work to convert. I don't think it generates 
links to undocumented stuff, so a solution may be to remove the 
documentation (just change /** to /*) on things that do not want to be 
seen, and change the xslt to copy all the produced docs.

I think also doxygen does spuriously generate some links to non-existent 
targets.

> Or are duplicates perhaps due to us having, say, struct wl_display a
> different thing on server vs. client?

The duplicates are due mostly to wl_list (and similar things) being 
documented twice. But I think doxygen does generate some identical tags 
for the server and client documentation. The solution may be to edit one 
of these and add an extra letter to all the tags so there are no 
conflicts. Telling doxygen to document both in one pass caused it to mix 
all the calls together, probably a bad idea.
On 11/26/2014 10:22 AM, Bill Spitzak wrote:
> On 11/25/2014 11:52 PM, Pekka Paalanen wrote:
> 
>> Or are duplicates perhaps due to us having, say, struct wl_display a
>> different thing on server vs. client?
> 
> The duplicates are due mostly to wl_list (and similar things) being
> documented twice. But I think doxygen does generate some identical tags
> for the server and client documentation. The solution may be to edit one
> of these and add an extra letter to all the tags so there are no
> conflicts. Telling doxygen to document both in one pass caused it to mix
> all the calls together, probably a bad idea.

I definitely think this sounds like an issue I should look into. One of
the projects I worked on was to figure out how to create design
documents from doxygen, and to coordinate design docs from multiple
teams working on multiple projects/features.

One key to getting overall documentation to work was to coordinate
identifiers to either end up with different ones or unified ones on a
case by case basis.

The *ideal* would be to get a single unified Doxygen pass working.
However, it does warrant investigation as to how close to that a
pragmatic solution appropriate to Wayland would get us. Two passes is
not that bad. Once I start to get details and options figured out it
definitely looks like Bill will be able to give feedback and guidance.


Jon A. Cruz
On Wed, 26 Nov 2014 11:24:28 -0800
"Jon A. Cruz" <jonc@osg.samsung.com> wrote:

> 
> 
> On 11/26/2014 10:22 AM, Bill Spitzak wrote:
> > On 11/25/2014 11:52 PM, Pekka Paalanen wrote:
> > 
> >> Or are duplicates perhaps due to us having, say, struct wl_display a
> >> different thing on server vs. client?
> > 
> > The duplicates are due mostly to wl_list (and similar things) being
> > documented twice. But I think doxygen does generate some identical tags
> > for the server and client documentation. The solution may be to edit one
> > of these and add an extra letter to all the tags so there are no
> > conflicts. Telling doxygen to document both in one pass caused it to mix
> > all the calls together, probably a bad idea.
> 
> I definitely think this sounds like an issue I should look into. One of
> the projects I worked on was to figure out how to create design
> documents from doxygen, and to coordinate design docs from multiple
> teams working on multiple projects/features.
> 
> One key to getting overall documentation to work was to coordinate
> identifiers to either end up with different ones or unified ones on a
> case by case basis.
> 
> The *ideal* would be to get a single unified Doxygen pass working.
> However, it does warrant investigation as to how close to that a
> pragmatic solution appropriate to Wayland would get us. Two passes is
> not that bad. Once I start to get details and options figured out it
> definitely looks like Bill will be able to give feedback and guidance.

Please do.

If you need it, it is perfectly ok to have server and client side
passes separate. I'd like them to be separate HTML pages, too. It
doesn't hurt, if we happen to get duplicate documentation for things
like wl_list, one for server and one for client. The important thing is
to never mix up server stuff with client stuff.

Btw. libwayland-cursor is client side stuff and a separate library.

For example: struct wl_display is very different between server and
client. 

Struct wl_buffer has three completely different meanings:

- client side public API: it is a syntactic type without an actual
  definition: the real struct behind it is wl_proxy.

- server side public API: it is a deprecated real type with public
  members.

- libwayland internal API: a ring byte buffer, completely contained in
  src/connection.c, used by both server and client side internal code.

Luckily connection.c probably should not be included in the generated
docs, so we can overlook the third meaning.


Thanks,
pq