More monodocer

I'm attaching a patch that makes these changes to
monodocer/monodocs2html:

monodocer:

Fix a problem in tracking which members are already
documented during an
update by tracking members by their signature, instead of
MemberInfo.

Document custom attributes with the new 2.0
CustomAttributeData classes,
so that the attribute constructor call can be reconstructed.

Hide the System.Runtime.InteropServices.Out attribute.

monodocs2html:

Include inherited members in the member listing for a type,
if the
type's ancestor types are documented in the same set.

Provided no one has objections, I'll commit.

-- 
- Joshua Tauberer

http://razor.occams.info

"Strike up the klezmer and start acting like a man.
You're
about to have a truth-mitzvah."  -- The Colbert Report
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Sun, 2006-10-08 at 18:18 -0400, Joshua Tauberer wrote:
> monodocs2html:
> 
> Include inherited members in the member listing for a
type, if the
> type's ancestor types are documented in the same set.

 -1182,11
+1241,31 
                        <xsl:sort
select="Parameters/Parameter/Type"/>
                        
                        <xsl:variable
name="linkid">
+                               <xsl:if
test="not(parent::Members/FullName =
$TypeFullName)">
+                                      
<xsl:call-template name="GetLinkTarget">
+                                              
<xsl:with-param name="type"
select="parent::Members/FullName" />
+                                              
<xsl:with-param name="local-suffix"/>
+                                              
<xsl:with-param name="remote"/>
+                                              
<xsl:with-param name="empty-if-this"
select="1"/>
+                                      
</xsl:call-template>
+                               </xsl:if>
+
+                              
<xsl:text>#</xsl:text>
                                <xsl:call-template
name="GetLinkId" >
-                                       <xsl:with-param
name="type" select="../.." />
+                                       <xsl:with-param
name="type" select="parent::Members"
/>
                                        <xsl:with-param
name="member" select="." />
                                </xsl:call-template>
                        </xsl:variable>
+                       
+                       <xsl:variable
name="isinherited">
+                               <xsl:if
test="not(parent::Members/FullName =
$TypeFullName)">
+                                       (<i>Inherited
from
+                                      
<xsl:call-template name="maketypelink">
+                                              
<xsl:with-param name="type"
select="parent::Members/FullName"/>
+                                              
<xsl:with-param name="wrt"
select="$TypeNamespace"/>
+                                      
</xsl:call-template>.</i>)
+                               </xsl:if>
+                       </xsl:variable>

You might want to wrap the "(<i>Inherited
from..." and ")" within
<xsl:text/> so that extra whitespace isn't introduced
in the output
document.

Also, you might want to modify DocTest.cs so that
GenericBase`1 has some
members, so that we can see the effect of this option in the
regression
tests.

 -1197,9
+1276,9 
                                        <td>
                                        <div>
                                        <b>
-                                       <a
href="#{$linkid}">
+                                       <a
href="{$linkid}">

Why'd you get rid of the "#" from the href here
and in other spots?  I
don't see any changes in GetLinkId() that would remove the
need for
this.

Index:
DocTest/html.expected/Mono.DocTest.Generic/MyList`1.html
============================================================
=======
--- DocTest/html.expected/Mono.DocTest.Generic/MyList`1.html
   (revision 66435)
+++ DocTest/html.expected/Mono.DocTest.Generic/MyList`1.html
   (working copy)
 -98,7
+98,7 
               <td>
                 <b>
                   <a
href="#M:Mono.DocTest.Generic.MyList`1.GetHelper`2"
;>GetHelper&lt;U,V&gt;</a>
-                </b>()<nobr>:<a
href="../Mono.DocTest.Generic/MyList`1+Helper`2.html&qu
ot;>MyList&lt;T&gt;.Helper&lt;U,V&gt;<
/a></nobr><div>To be
added.</div></td>
+                </b>()<nobr> : <a
href="../Mono.DocTest.Generic/MyList`1+Helper`2.html&qu
ot;>MyList&lt;T&gt;.Helper&lt;U,V&gt;<
/a></nobr><div>To be
added.</div></td>
             </tr>
             <tr valign="top">
               <td>
 -129,7
+129,7 
               </td>
               <td>
                 <b>
-                  <a
href="#M:Mono.DocTest.Generic.MyList`1.UseHelper`2(Mono
.DocTest.Generic.MyList{`1}.Helper{``1,``2})">UseHel
per&lt;U,V&gt;</a>
+                  <a
href="#M:Mono.DocTest.Generic.MyList`1.UseHelper`2(Mono
.DocTest.Generic.MyList.Helper{``1,``2})">UseHelp
er&lt;U,V&gt;</a>
                 </b>(<a
href="../Mono.DocTest.Generic/MyList`1+Helper`2.html&qu
ot;>MyList&lt;T&gt;.Helper&lt;U,V&gt;<
/a>)<div>To be added.</div></td>
             </tr>
           </table>

Your changes broke something:  should continue to be {`1}
within the
href="..." text.

 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Sun, 2006-10-08 at 21:21 -0400, Jonathan Pryor wrote:
> On Sun, 2006-10-08 at 18:18 -0400, Joshua Tauberer
wrote:
> > monodocs2html:
> > 
> > Include inherited members in the member listing
for a type, if the
> > type's ancestor types are documented in the same
set.
>  -1197,9 +1276,9 
>                                         <td>
>                                         <div>
>                                         <b>
> -                                       <a
href="#{$linkid}">
> +                                       <a
href="{$linkid}">
> 
> Why'd you get rid of the "#" from the href
here and in other spots?  I
> don't see any changes in GetLinkId() that would remove
the need for
> this.

I missed where you use '#' earlier in stylesheet.xsl.  Never
mind.

Still not sure why MyList`1.html broke.

 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Sun, 2006-10-08 at 21:21 -0400, Jonathan Pryor wrote:
> On Sun, 2006-10-08 at 18:18 -0400, Joshua Tauberer
wrote:
> > monodocs2html:
> > 
> > Include inherited members in the member listing
for a type, if the
> > type's ancestor types are documented in the same
set.
> Index:
DocTest/html.expected/Mono.DocTest.Generic/MyList`1.html
>
============================================================
=======
> ---
DocTest/html.expected/Mono.DocTest.Generic/MyList`1.html   
(revision 66435)
> +++
DocTest/html.expected/Mono.DocTest.Generic/MyList`1.html   
(working copy)
>  -98,7 +98,7 
>                <td>
>                  <b>
>                    <a
href="#M:Mono.DocTest.Generic.MyList`1.GetHelper`2"
;>GetHelper&lt;U,V&gt;</a>
> -                </b>()<nobr>:<a
href="../Mono.DocTest.Generic/MyList`1+Helper`2.html&qu
ot;>MyList&lt;T&gt;.Helper&lt;U,V&gt;<
/a></nobr><div>To be
added.</div></td>
> +                </b>()<nobr> : <a
href="../Mono.DocTest.Generic/MyList`1+Helper`2.html&qu
ot;>MyList&lt;T&gt;.Helper&lt;U,V&gt;<
/a></nobr><div>To be
added.</div></td>
>              </tr>
>              <tr valign="top">
>                <td>
>  -129,7 +129,7 
>                </td>
>                <td>
>                  <b>
> -                  <a
href="#M:Mono.DocTest.Generic.MyList`1.UseHelper`2(Mono
.DocTest.Generic.MyList{`1}.Helper{``1,``2})">UseHel
per&lt;U,V&gt;</a>
> +                  <a
href="#M:Mono.DocTest.Generic.MyList`1.UseHelper`2(Mono
.DocTest.Generic.MyList.Helper{``1,``2})">UseHelp
er&lt;U,V&gt;</a>
>                  </b>(<a
href="../Mono.DocTest.Generic/MyList`1+Helper`2.html&qu
ot;>MyList&lt;T&gt;.Helper&lt;U,V&gt;<
/a>)<div>To be added.</div></td>
>              </tr>
>            </table>
> 
> Your changes broke something:  should continue to be
{`1} within the
> href="..." text.

I imagine that this change was created due to this change in
stylesheet.xsl:

 -1182,11
+1241,31 
                        <xsl:sort
select="Parameters/Parameter/Type"/>
                        
                        <xsl:variable
name="linkid">
+                               <xsl:if
test="not(parent::Members/FullName =
$TypeFullName)">
+                                      
<xsl:call-template name="GetLinkTarget">
+                                              
<xsl:with-param name="type"
select="parent::Members/FullName" />
+                                              
<xsl:with-param name="local-suffix"/>
+                                              
<xsl:with-param name="remote"/>
+                                              
<xsl:with-param name="empty-if-this"
select="1"/>
+                                      
</xsl:call-template>
+                               </xsl:if>
+
+                              
<xsl:text>#</xsl:text>
                                <xsl:call-template
name="GetLinkId" >
-                                       <xsl:with-param
name="type" select="../.." />
+                                       <xsl:with-param
name="type" select="parent::Members"
/>
                                        <xsl:with-param
name="member" select="." />
                                </xsl:call-template>
                        </xsl:variable>

I'm not too familiar with the extended select syntax, but I
imagine that
"../.." isn't the same as
"paremt::Members".  At least, this is the only
reason I can think of for GetLinkId to return the wrong
string,
especially since I don't see any other related change.

 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Jonathan Pryor wrote:
> You might want to wrap the "(<i>Inherited
from..." and ")" within
> <xsl:text/> so that extra whitespace isn't
introduced in the output
> document.

Good point.

> Also, you might want to modify DocTest.cs so that
GenericBase`1 has some
> members, so that we can see the effect of this option
in the regression
> tests.

Right, I thought of that after sending the patch.  That also
helped
explain the other problem you found:

> Your changes broke something:  should continue to be
{`1} within the
> href="..." text.

I needed to add type name escaping in two places.

> Why'd you get rid of the "#" from the href
here and in other spots?  I
> don't see any changes in GetLinkId() that would remove
the need for
> this.

What happens now is that in the template
GetInheritedMembers, it
recursively assembles some content like this:

<Members Name="Object"
FullName="System.Object">
  <Member ...
  </Member>
</Members>
<Members Name="MyClass"
FullName="MyNs.MyClass">
  <Member ...
  </Member>
</Members>

Then when listing a member, rather than using ../.. to get
to the type
(which is no longer in the tree of this content), it uses
parent::Members to go up a level to get the declaring type
of the
member.  Further, when assembling the link, it needs to put
a file path
before the #, which is why the # moved from the a nodes up
earlier.

-- 
- Joshua Tauberer

http://razor.occams.info

"Strike up the klezmer and start acting like a man.
You're
about to have a truth-mitzvah."  -- The Colbert Report
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

I see that you committed your changes, and I'm seeing
changes that I
don't understand.

For example, after running the check-monodocer test I see:

-  <Base>
-    <BaseTypeName>System.Object</BaseTypeName>
-  </Base>
+  <Base />
+  <BaseTypeName>System.Object</BaseTypeName>

But I don't see any explanation for this in the ChangeLog.

Actually, it's causing a failure in the unit tests for me:

diff --exclude=.svn -rup
DocTest/en.expected/Mono.DocTest/Color.xml
DocTest/en.actual/Mono.DocTest/Color.xml
--- DocTest/en.expected/Mono.DocTest/Color.xml  2006-10-09
21:50:30.000000000 -0400
+++ DocTest/en.actual/Mono.DocTest/Color.xml    2006-10-10
07:22:09.000000000 -0400
 -4,9
+4,8 
     <AssemblyName>DocTest</AssemblyName>
     <AssemblyVersion>0.0.0.0</AssemblyVersion>
   </AssemblyInfo>
-  <Base>
-    <BaseTypeName>System.Enum</BaseTypeName>
-  </Base>
+  <Base />
+  <BaseTypeName>System.Enum</BaseTypeName>

Among many others.

Any idea about what's happening here?

 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Jonathan Pryor wrote:
> I see that you committed your changes, and I'm seeing
changes that I
> don't understand.
> 
> For example, after running the check-monodocer test I
see:
> 
> -  <Base>
> -   
<BaseTypeName>System.Object</BaseTypeName>
> -  </Base>
> +  <Base />
> + 
<BaseTypeName>System.Object</BaseTypeName>

That's weird.  Obviously I goofed something (in my second
commit
probably)...

-- 
- Joshua Tauberer

http://razor.occams.info

"Strike up the klezmer and start acting like a man.
You're
about to have a truth-mitzvah."  -- The Colbert Report
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Tue, 2006-10-10 at 07:37 -0400, Joshua Tauberer wrote:
> Jonathan Pryor wrote:
> > I see that you committed your changes, and I'm
seeing changes that I
> > don't understand.
> > 
> > For example, after running the check-monodocer
test I see:
> > 
> > -  <Base>
> > -   
<BaseTypeName>System.Object</BaseTypeName>
> > -  </Base>
> > +  <Base />
> > + 
<BaseTypeName>System.Object</BaseTypeName>
> 
> That's weird.  Obviously I goofed something (in my
second commit
> probably)...

Yes, your 2nd commit caused it.

A fix is to change line 699:

-WriteElementText(root, "Base/BaseTypeName",
basetypename);
+WriteElementText(basenode, "BaseTypeName",
basetypename);

However, I'm not sure *why* this would be necessary, since
WriteElementText() calls WriteElement(), which splits the
string along
'/', so the original *should* be correct (as
SelectSingleNode("Base")
should return basenode, allowing BaseTypeName to be created
underneath
Base).  Very confusing.

Another problem is that the position of /Type/TypeParameters
has changed
from DocTest/en.expected -- it used to be after the
/Type/Docs node, and
now it's before the /Type/Base node.

The *real* problem is that the position of
/Type/TypeParameters changes
between the initial documentation generation and on update. 
Initial
creation places it before /Type/Base, while an update places
it last.
This creates spurious differences.

 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

> A fix is to change line 699:
> 
> -WriteElementText(root, "Base/BaseTypeName",
basetypename);
> +WriteElementText(basenode, "BaseTypeName",
basetypename);
> 
> However, I'm not sure *why* this would be necessary,

There was a bug in WriteElement.  It didn't traverse down
the nodes
properly if a node in the path (in this case Base) already
existed.

> Another problem is that the position of
/Type/TypeParameters has changed
> from DocTest/en.expected -- it used to be after the
/Type/Docs node, and
> now it's before the /Type/Base node.
> 
> The *real* problem is that the position of
/Type/TypeParameters changes
> between the initial documentation generation and on
update.

Right, I just fixed it so it stays at the top.

Everything is committed and *should* work now.  I hope...

-- 
- Joshua Tauberer

http://razor.occams.info

"Strike up the klezmer and start acting like a man.
You're
about to have a truth-mitzvah."  -- The Colbert Report
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list