The code generator adds comments to the code that can be read by documentation generators. It would be nice if the comments could be customized so that the documentation ends up with something more useful than "The XXX property of the Entity YYY".

I can modify the comments in the code after it's generated, but this gets to be cumbersome if I have to regenerate the base classes afterward.

Perhaps the designer could read any descriptive information for tables and columns stored in the database, then allow us to edit and save the comments as part of the project.

I'm not sure but sinds june 24th when v1.0.2004.1 of the designer was released comments of entity properties look like:

    /// <summary>
    /// The City property of the Entity Customer<br/><br/>
    /// 
    /// </summary>
    /// <remarks>
    /// Mapped on table field: "Customers"."City"<br/>
    /// Table field type characteristics (type, precision, scale, length): NVarChar, 0, 0, 15
    /// Table field behavior characteristics (is nullable, is PK, is identity): true, false, false
    /// </remarks>

Yes, we also use SQL server comments to put some remarks on tables and fields. It'll be very nice if these comments are retrieved and put into generated code

Fabrice wrote:

Yes, we also use SQL server comments to put some remarks on tables and fields. It'll be very nice if these comments are retrieved and put into generated code

You mean hte custom properties you can retrieve from the db and store in the code?

Otis wrote:

I'm not sure but sinds june 24th when v1.0.2004.1 of the designer was released comments of entity properties look like:

    /// <summary>
    /// The City property of the Entity Customer<br/><br/>
    /// 
    /// </summary>
    /// <remarks>
    /// Mapped on table field: "Customers"."City"<br/>
    /// Table field type characteristics (type, precision, scale, length): NVarChar, 0, 0, 15
    /// Table field behavior characteristics (is nullable, is PK, is identity): true, false, false
    /// </remarks>

These comments are better than nothing, but not really useful if one is generating proper class documentation. I'd like to be able to edit, in the designer, what will be generated as the comments for each property.

For example, when I generate the database I may include a description of the City column; it would be good to have that propagate to the code. Otherwise I have to go back to the data dictionary to find out what "City" means.

A free-form editor would be best so that people using a commenting style other than the XML Help style could edit in their preferred format (I use Doc-o-Matic, which is much more robust than XML Help).

Oh but that is possible now.

In the database, you could have defined description texts for example. These are read as 'custom properties' for tables, fields, procedures etc. (v1.0.2004.1 of the designer required). You can add custom properties to a field in the designer. These are then generated into the comments of a property which is representing a field. The empty line above </summary> will contain per line a name-value pair for each custom property you have defined.

I'm not sure if you wnt that, or if you want something completely different, as you seem to suggest that you want different output than the XML comments.

I've not understand, sorry

I've a comment on a field in the database When I refresh de schema, in the "Element to read from the database schemas" I've the checkbox "Custom properties" checked. After the refresh, I see the comment in the catalog explorer under the custom propertiy name "MS_Description"

But .. I don't see the custom property in the entity editor (Entities > MyEntity > "Fields mapped on database field"). I only see it in catalog explorer And it's not visible in the generated class of course.

PS : after that, when I want to regenerate again, the checkbox "Custom properties" is still enable so I suppose it's because I don't use any custom properties yet.

Since we're talking auto-created comments in code, I'll point this out.

I recall, (but don't have an example in front of me) that the VB templates create comments like this:

' /// This is a comment.

While the C# does this:

/// This is a comment.

Lovely, but it interferes with ndoc, which generates CHM files from comments on classes. NDoc is looking for the three marks, the single quote in VB, the slash in C#, and is confused by the above VB commenting. In short, ndoc doesn't work for VB generated code.

Gee, that's too many lines to change in the templates, is it?

Again, this was true last time I look for it, some six months ago. You may have fixed it since, and I'm not near the code right now.

No I haven't changed VB.NET code comments into ''', as it wasn't clear for a long time what MS would choose for VB.NET code comments.

Frankly I don't think the change is worth the effort (as the effort is pretty big). If you want to generate documentation from your code, generate a C# variant, generate docs from that.

Fabrice wrote:

I've not understand, sorry I've a comment on a field in the database When I refresh de schema, in the "Element to read from the database schemas" I've the checkbox "Custom properties" checked. After the refresh, I see the comment in the catalog explorer under the custom propertiy name "MS_Description"

But .. I don't see the custom property in the entity editor (Entities > MyEntity > "Fields mapped on database field"). I only see it in catalog explorer And it's not visible in the generated class of course.

Custom properties are added to entities when you create an entity and the catalog contains custom properties AND you've checked the option Retrieve DB Custom Properties in the project properties.

So if you first created entities, and you've now refreshed the catalog, these custom properties are not showing up.

Frankly I don't think the change is worth the effort

I agree.