March 15, 2010 at 6:53 am
GSquared, I like the idea of the parameter. That would be very handy to know during the creation of modification of some DDL statement. That could then be exposed later in documentation or when someone has a question about a field.
March 15, 2010 at 8:00 am
Steve Jones - Editor (3/15/2010)
GSquared, I like the idea of the parameter. That would be very handy to know during the creation of modification of some DDL statement. That could then be exposed later in documentation or when someone has a question about a field.
I posted it on connect, https://connect.microsoft.com/SQLServer/feedback/details/541978/ddl-inline-documentation#
Since it's a minor need and non-trivial change to how the T-SQL engine would parse out DDL commands, I wouldn't expect Microsoft to act on it with any alacrity. But I posted it anyway. Feel free to comment/vote on it, of course.
- Gus "GSquared", RSVP, OODA, MAP, NMVP, FAQ, SAT, SQL, DNA, RNA, UOI, IOU, AM, PM, AD, BC, BCE, USA, UN, CF, ROFL, LOL, ETC
Property of The Thread
"Nobody knows the age of the human race, but everyone agrees it's old enough to know better." - Anon
March 15, 2010 at 8:33 am
Voted and added this comment
"I like the idea of somehow adding details about a change. This would be great for an audit log. If there were a parameter per column, or even per item, this could be stored in extended properties as well, allowing for more detailed documentation about an object."
March 15, 2010 at 9:26 am
SQL script files are free format text files.
If we turn that into a structured format, e.g. XML, users will strart filling up various tags to document along with the coding process.
There can be various XML templates made avaible for the developers to use the structure to code for various types of SQL objects.
March 15, 2010 at 2:43 pm
"...The XML Documentation facility built into all the .NET languages..." - I wish! VB.NET supports intellisense so the hovering images of what something does will be supported if you are looking at something generated in another language. I tried all I could think of to start that facility until I read specifically that it isn't supported in VB.NET.
Yes, it would be nice if that facility was built into SQL as well, however the intellisense currently built into SQL 2008 is 1 out of 10 times helpful and 9 out of 10 clueless, distracting, and throws me off. It's like a 3 year old with no clue of what you are doing trying to be helpful. In other languages, you type "Me." or "this." to tell the system, yes, I expect some help.
That "mind reading" comment made elsewhere belongs with the Microsoft supplied intellisense, which is very apt. And yes, it isn't a full-blown documentation tool, but at least you can get a 1 line reminder of what something is for, at least in your own coding practices.
March 15, 2010 at 3:32 pm
The XML Documentation facility built into all the .NET languages..." - I wish! VB.NET supports intellisense so the hovering images of what something does will be supported if you are looking at something generated in another language. I tried all I could think of to start that facility until I read specifically that it isn't supported in VB.NET
For details of C# XML Documentation see XML Documentation Comments (C# Programming Guide). For the same in F# see XML Documentation (F#). The latter reference contains the quote
The support in F# for generating documentation from comments is the same as that in other .NET Framework languages. As in other .NET Framework languages, the -doc compiler option enables you to produce an XML file that contains information that you can convert into documentation by using a tool such as Sandcastle
. You can most certainly use XML Documentation in VB.NET. See Documenting Your Code with XML (Visual Basic) The compiler switch is the same, and there are several links in the URLs I've given that will explain the system in detail. There is even XML documentation support in IronPython. I hope that is useful.
Best wishes,
Phil Factor
March 15, 2010 at 4:34 pm
Thanks for the documentation. I supposedly have version 3.5. I haven't figured out how and where to put /doc:filename in Visual Studio. It appears to be a command line option. One of the first things I tried was ''', also '', then just '. Nothing produces the XML framework automatically generated by /// in C#.
If I have to write a separate XML file to store my documentation, it just isn't worth the work. Neither is manually writing in all the ''' XML formatting inline above each object/routine, especially if my VS won't recognize it. (My Intellisense DEFINITELY does NOT recognize it using the ''' like /// in C# and XML formatting like C#.)
MY VB help specifically states XML documentation is NOT supported in VB.NET.
Whatever version I've got, it sucks.
This version will not compile C# in VS (Developer's version bought specifically for VB.NET.), but it does support XML documentation in C#.
March 15, 2010 at 6:53 pm
GSquared (3/15/2010)
Steve Jones - Editor (3/15/2010)
GSquared, I like the idea of the parameter. That would be very handy to know during the creation of modification of some DDL statement. That could then be exposed later in documentation or when someone has a question about a field.I posted it on connect, https://connect.microsoft.com/SQLServer/feedback/details/541978/ddl-inline-documentation#
Since it's a minor need and non-trivial change to how the T-SQL engine would parse out DDL commands, I wouldn't expect Microsoft to act on it with any alacrity. But I posted it anyway. Feel free to comment/vote on it, of course.
TO GSquared - Unfortunately you misunderstood my comments, I was referring to DDL triggers that means you could query system view and retrieve SP/UDF parameters meta data AFTER data object had been modified. Parameters definition could be easily assembled into XML document and updated under key "Parameters" under SP/UDF Extended Properties.
March 16, 2010 at 6:19 am
irozenberg (3/15/2010)
GSquared (3/15/2010)
Steve Jones - Editor (3/15/2010)
GSquared, I like the idea of the parameter. That would be very handy to know during the creation of modification of some DDL statement. That could then be exposed later in documentation or when someone has a question about a field.I posted it on connect, https://connect.microsoft.com/SQLServer/feedback/details/541978/ddl-inline-documentation#
Since it's a minor need and non-trivial change to how the T-SQL engine would parse out DDL commands, I wouldn't expect Microsoft to act on it with any alacrity. But I posted it anyway. Feel free to comment/vote on it, of course.
TO GSquared - Unfortunately you misunderstood my comments, I was referring to DDL triggers that means you could query system view and retrieve SP/UDF parameters meta data AFTER data object had been modified. Parameters definition could be easily assembled into XML document and updated under key "Parameters" under SP/UDF Extended Properties.
I wasn't responding to your comment. Steve replied to me, and I replied to him. What you're suggesting is what I said could be an alternative to the idea of a specific parameter for the DDL create/alter commands.
- Gus "GSquared", RSVP, OODA, MAP, NMVP, FAQ, SAT, SQL, DNA, RNA, UOI, IOU, AM, PM, AD, BC, BCE, USA, UN, CF, ROFL, LOL, ETC
Property of The Thread
"Nobody knows the age of the human race, but everyone agrees it's old enough to know better." - Anon
March 16, 2010 at 10:11 am
I wrote a documentation tool called SqlSpec that supports SQL Server as well as 13 other platforms. It allows you to add an xml comment header to each proc/view/function etc just as people are discussing here. When you generate the docs, it will parse that header and create sections in the docs with that content, such as a change history, etc.
Also there's an extended properties editor that allows you to easily add comments to all your objects. Of course those comments are fetched when the tool runs and put in the docs.
link to it is in my sig. 🙂
---------------------------------------
elsasoft.org
March 22, 2010 at 5:42 am
GSquared (3/15/2010)
Since it's a minor need and non-trivial change to how the T-SQL engine would parse out DDL commands, I wouldn't expect Microsoft to act on it with any alacrity. But I posted it anyway. Feel free to comment/vote on it, of course.
They acted with fairly great alacricity to close it as "won't fix". It was closed before I could vote for it.
Tom
March 22, 2010 at 1:00 pm
I would love to have the same XML documentation capabilities in SQL Server as in Visual Studio. I fact, we're using the same notation even though you can't do anything with it right now. It provides commonality between comments in our source code and database "code". Feeding this XML into Sandcastle for documentation is a tremendous asset, especially for projects with hundreds of classes and thousands of members.
May 2, 2011 at 11:49 am
Here is one more Free Tool to document Sql Server
Viewing 13 posts - 16 through 27 (of 27 total)
You must be logged in to reply to this topic. Login to reply