C# XML documentation of Linq to SQL

Question

How to document the classes & properties & functions that are generated automatically using LINQ to SQL DBML?

I managed to provide documentation to the datacontext class by defining the same partial class in another file with <summary> so it won't be removed if the DBML got refreshed

/// <summary>  
/// Linq to SQL datacontext  
/// </summary>  
public partial class LinqDBDataContext {  

}

This would work for table mapping class with one downside is having to manually maintain the separate class for added/removed tables.

another thing..I have comments-like-documentation(author, date and description) in the stored procedure, shouldn't be also extracted into the code file as the function's documentation?

-- =============================================
-- Author:      <Katia Aleid>
-- Create date: <2015-04-01>
-- Description: <Performs search for the users>
-- =============================================
ALTER PROCEDURE [dbo].[SearchUsers] ....

is it acceptable to exclude the DBML form C# documentation and have separate database documentation instead?

Marc Gravell Marc Gravell · Accepted Answer · 2015-04-14T10:08:35

Comments inside a stored procedure are unlikely to be parseable by SqlMetal; at a push, it could access the MS_Description extended metadata, if you've assigned some - however, I would not expect it to do that. Looking inside the dbml metadata, there isn't anywhere obvious to store or edit additional comments, so frankly I suspect the answer here is: you don't. You shouldn't edit the *.designer.cs, because that can be regenerated at random.

C# XML documentation of Linq to SQL

1 Answers