xml comments

[Yechezkal Gutfreund]

Just started to use these. When I run the Code Comments web reports, the
following
snippet does not seem to understand the <list> <item> etc, tags. I am using
VS2003.

I cannot get <see> or <see> also to work in <summary> or directly after
</summary>


/// <summary>

/// Setup the StationMaster:

/// <list>

/// <item>Load XML packet</item>

/// <item>Create TCP client</item>

/// </list>

/// </summary>

/// <param name="myGUI">Handle for the StationMaster user interface</param>

 

[Rick Strahl [MVP]]

I think the docs are wrong on this. The format is something like this:

/// <item>
/// <term>test item</term>
/// <description>aDescription</description>
/// </item>

They're always in pairs for a two column table I think.

+++ Rick ---

--

Rick Strahl
West Wind Technologies
http://www.west-wind.com/
http://www.west-wind.com/wwHelp

 

[Yechezkal Gutfreund]

No it it still spits out all elements <whaterver tag> That is inside the
summary as if it was
simple text. The same thing applies to <see> and <seealso> tags.

If I take these tags out of the <summary> block, then it just ignores them.

 

[Jacob Yang [MSFT]]

Hi Yechezkal ,

I am testing your code on my side and will contact you as soon as possible.
More time is needed. Thank you for your understanding.

Best regards,

Jacob Yang
Microsoft Online Partner Support
<MCSD>
Get Secure! ¨C www.microsoft.com/security
This posting is provided ¡°as is¡± with no warranties and confers no rights.

 

[Yechezkal Gutfreund]

Ok. So the list items seems to be my poor understanding of the structure of
lists.

But I am still stuck on the <seealso> tag.

I place these two complete listings in two seperate files and then do a
solution build. The are both
part of the same project and namespace. But the don't seem to be able to
cross refernce:

# region Included Libraries

//--------------------------------------------------------------------------
---------------

// StationMaster - Manage the local PDA copy of the TeamSpace

//

// Copyright 2003, Kesser Technical Group, Inc. All rights reserved

//

// Creation: 04-Aug-2003

// Authors: YSG

// Versions:

// 0.01 Define instantiation

//--------------------------------------------------------------------------
---------------

using System;

using System.Xml;

using System.IO;

using System.Net;

using System.Net.Sockets;

# endregion

namespace KTGInc

{

/// <summary>

/// Maintiains a replicated copy of a TeamSpace for a PTMW station.

/// The StationMaster subscribes to the Orchestrator and receives

/// update packets for sprite propetry changes. It also receives new

/// sprite values from the PTMW Flash program, and publishes them to

/// the Orchestrator. The StationMaster is responsible for maintaining

/// the copy when offline, and doing a merge and update when re-connected.

/// <seealso cref="KTGInc.StationMasterGUI"/>

/// </summary>

public class StationMaster

{

#region Class Members, Instantiation and Destruction

private StationMasterGUI myGUI; // Pointer to the User Interface object

private XmlDocument outPacket = new XmlDocument(); // Holds the outgoing xml
packet;

private string packetFile = "Packet.xml"; // File name for template contents
of outPacket

private string orchHost = "BINA"; // Name of Orchestrator server host

private int orchPort = 7700; // Port for Orchestrator on server

private NetworkStream oStream; // output stream to Orchestrator

/// <summary>

/// Setup the StationMaster:

/// <list>

/// <item><term>Get XML template for packet</term></item>

/// <item><term>Create TCP client</term></item>

/// </list>

/// </summary>

/// <param name="myGUI">Handle for the StationMaster user interface</param>

public StationMaster(StationMasterGUI theGUI)

{

myGUI = theGUI;

string appPath = Path.GetDirectoryName(

System.Reflection.Assembly.GetExecutingAssembly().GetName().CodeBase.ToStrin
g());

outPacket.PreserveWhitespace = true;

outPacket.Load(appPath + "\\" + packetFile);

myGUI.PacketText = outPacket.OuterXml;

}

# endregion

# region Public Methods

/// <summary>

/// Attach to the Orchestrator, and start listening for messages

/// </summary>

/// <returns>true if connection worked</returns>

public void Connect()

{

TcpClient serverSocket = new TcpClient(this.orchHost, this.orchPort);

oStream = serverSocket.GetStream();

}

# endregion

# region Private Methods

# endregion

# region Property Methods

# endregion

#region Event Handlers


#endregion

}

}


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

# region Included Libraries

//--------------------------------------------------------------------------
---------------

// StationMasterGUI - User interface for the Station Master

//

// Copyright 2003, Kesser Technical Group, Inc. All rights reserved

//

// Creation: 04-Aug-2003

// Authors: YSG

// Versions:

// 0.01 Add action menu, packetbox, timing labels and boxes

//--------------------------------------------------------------------------
---------------

using System;

using System.Drawing;

using System.Collections;

using System.Windows.Forms;

using System.Data;

# endregion

namespace KTGInc

{

/// <summary>

/// The StationMasterGUI manages the user inteface fot the PDA's
StationMaster. It

/// has a menu of actions for actions such as starting the connect, and
dispays status

/// information about the health and state of the StationMaster.

/// <seealso cref="StationMaster"/>

/// </summary>



public class StationMasterGUI : System.Windows.Forms.Form

{

#region Class Members, Instantiation and Destruction

private System.Windows.Forms.MainMenu actionMenu; // Toolbar Menu for S.M.
actions

private System.Windows.Forms.MenuItem actionsTab; // ActonMenu item listed
on Toolbar

private System.Windows.Forms.MenuItem sendAct; // Action for Sending packet

private System.Windows.Forms.TextBox packetBox; // background for statistics

private System.Windows.Forms.Label startLabel; // label start box

private System.Windows.Forms.Label startBox; // holds start time

private System.Windows.Forms.Label stopLabel; // label stop box

private System.Windows.Forms.Label timeLabel; // label time box

private System.Windows.Forms.Label stopBox; // holds stop time

private System.Windows.Forms.Label timeBox;

private System.Windows.Forms.MenuItem connectAct;

private System.Windows.Forms.Panel statsPanel; // Action for connecting to
Orchestrator

private StationMaster myStationMaster; // handle for StationMaster object

/// <summary>

/// Create GUI, Initialize Forms, create StationMaster

/// </summary>

public StationMasterGUI()

{

//

// Required for Windows Form Designer support

//

InitializeComponent();

this.myStationMaster = new StationMaster(this);

}

/// <summary>

/// Clean up any resources being used.

/// </summary>

protected override void Dispose( bool disposing )

{

base.Dispose( disposing );

}

# endregion

#region Windows Form Designer generated code

/// <summary>

/// Required method for Designer support - do not modify

/// the contents of this method with the code editor.

/// </summary>

private void InitializeComponent()

{

System.Resources.ResourceManager resources = new
System.Resources.ResourceManager(typeof(StationMasterGUI));

this.actionMenu = new System.Windows.Forms.MainMenu();

this.actionsTab = new System.Windows.Forms.MenuItem();

this.sendAct = new System.Windows.Forms.MenuItem();

this.connectAct = new System.Windows.Forms.MenuItem();

this.packetBox = new System.Windows.Forms.TextBox();

this.statsPanel = new System.Windows.Forms.Panel();

this.timeBox = new System.Windows.Forms.Label();

this.stopBox = new System.Windows.Forms.Label();

this.timeLabel = new System.Windows.Forms.Label();

this.stopLabel = new System.Windows.Forms.Label();

this.startBox = new System.Windows.Forms.Label();

this.startLabel = new System.Windows.Forms.Label();

//

// actionMenu

//

this.actionMenu.MenuItems.Add(this.actionsTab);

//

// actionsTab

//

this.actionsTab.MenuItems.Add(this.sendAct);

this.actionsTab.MenuItems.Add(this.connectAct);

this.actionsTab.Text = "Actions";

//

// sendAct

//

this.sendAct.Text = "Send";

this.sendAct.Click += new System.EventHandler(this.SendAct_Click);

//

// connectAct

//

this.connectAct.Text = "Connect";

this.connectAct.Click += new System.EventHandler(this.ConnectAct_Click);

//

// packetBox

//

this.packetBox.Multiline = true;

this.packetBox.ScrollBars = System.Windows.Forms.ScrollBars.Both;

this.packetBox.Size = new System.Drawing.Size(240, 184);

this.packetBox.Text = "*empty*";

this.packetBox.WordWrap = false;

//

// statsPanel

//

this.statsPanel.BackColor = System.Drawing.Color.PaleGoldenrod;

this.statsPanel.Controls.Add(this.timeBox);

this.statsPanel.Controls.Add(this.stopBox);

this.statsPanel.Controls.Add(this.timeLabel);

this.statsPanel.Controls.Add(this.stopLabel);

this.statsPanel.Controls.Add(this.startBox);

this.statsPanel.Controls.Add(this.startLabel);

this.statsPanel.Location = new System.Drawing.Point(0, 192);

this.statsPanel.Size = new System.Drawing.Size(240, 80);

//

// timeBox

//

this.timeBox.Location = new System.Drawing.Point(56, 56);

this.timeBox.Size = new System.Drawing.Size(176, 16);

this.timeBox.Text = ".....";

//

// stopBox

//

this.stopBox.Location = new System.Drawing.Point(56, 32);

this.stopBox.Size = new System.Drawing.Size(176, 16);

this.stopBox.Text = ".....";

//

// timeLabel

//

this.timeLabel.Location = new System.Drawing.Point(8, 56);

this.timeLabel.Size = new System.Drawing.Size(40, 16);

this.timeLabel.Text = "Time:";

//

// stopLabel

//

this.stopLabel.Location = new System.Drawing.Point(8, 32);

this.stopLabel.Size = new System.Drawing.Size(40, 16);

this.stopLabel.Text = "Stop:";

//

// startBox

//

this.startBox.Location = new System.Drawing.Point(56, 8);

this.startBox.Size = new System.Drawing.Size(176, 16);

this.startBox.Text = ".....";

//

// startLabel

//

this.startLabel.Location = new System.Drawing.Point(8, 8);

this.startLabel.Size = new System.Drawing.Size(40, 16);

this.startLabel.Text = "Start:";

//

// StationMasterGUI

//

this.BackColor = System.Drawing.Color.OliveDrab;

this.Controls.Add(this.statsPanel);

this.Controls.Add(this.packetBox);

this.Icon = ((System.Drawing.Icon)(resources.GetObject("$this.Icon")));

this.Menu = this.actionMenu;

this.Text = "StationMaster";

}

#endregion

# region Public Methods

/// <summary>

/// The main entry point for the application.

/// </summary>

static void Main()

{

Application.Run(new StationMasterGUI());

}

# endregion

# region Private Methods

# endregion

# region Property Methods

/// <summary>

/// Get/Set the text from component that holds packet text (xml)

/// </summary>

public string PacketText

{

get { return this.packetBox.Text;}

set { this.packetBox.Text = value;}

}

# endregion

#region Event Handlers


private void ConnectAct_Click(object sender, System.EventArgs e)

{


}

private void SendAct_Click(object sender, System.EventArgs e)

{


}

#endregion

}

}

 

[Yechezkal Gutfreund]

The MSDN article was where I learned about the tags (I get the print copy of
MSDN also).

 

[Yechezkal Gutfreund]

I have done some searching of the ms news groups and it seems that both
<see> and <seealso>
are not supported by VS2003 make program documentation. An external program
called NDOC might
do this, but people complain that it is too complicated, or other
complaints.

 

[Yechezkal Gutfreund]

Jacob, I plugged this in directly in to my VS2003 project. I then tried:
Tools/Build Comment Web Pages.

No luck. If I have the box checked for include tags as text for security
purposes then
the tags appear as simple text (with the angle braces) in the summary. If I
turn
off that check box, then the text is all concatenated as one single
paragraph with now
list of any sort.