Optional Items
The “Optional Items” settings page contains some interesting options, such as the “Graphical Dependencies” option or the object grouping by file group.
Depending on your selections the Treeview might get adjusted and show or hide some items. Since I want to include the “Graphical Dependencies” in my final output, I need to check the appropriate checkbox, which in turn will result in that the Treeview item which gives me access to the corresponding settings page is visible.
The “Graphical Dependencies” functionality is powered by the same engine that is implemented in ApexSQL Clean.
I’ve described the engine in more detail in my paper on the ApexSQL Clean tool, so if you want to read more about it, you can find it here.
Tagged Comments
To me one of the most interesting features is the “Tagged Comments”, so I will explain it in more details. “Tagged Comments” are custom tags you can use to store individual and specific information about a given database object. They are stored together with the objects SQL statement.
This works for all supported database objects with the exception of tables and indexes. I’ll return to tagged comments on tables and indexes in just a moment. But let me first explain the usage of tagged comments on the other object types. To use tagged comments later on in the documentation process, you directly include the tags when you create an object. For example like this:
-- ##SUMMARY Sample Description1
-- ##SEEALSO TABLE dbo.authors
-- ##ISNEW 09.09.2006
create procedure [dbo].[sp1] @id int, --##PARAM @p1 The p1
@fname varchar(50) = 'D%', --##PARAM @fname last name
@salutation varchar(50) ='D%', --##PARAM @salutation salutation
@position char(10)
as
select * from dbo.authors
Since the “source code” for objects other than tables and indexes is stored by SQL Server in one of its system tables, ApexSQL Doc can directly retrieve the information from that system table when creating the documentation. However, these things are a bit different for tables and indexes. The generating source code for that kind of objects is not stored inside SQL Server and therefore cannot be directly retrieved. In order to use tagged comments on tables and indexes now, you need to specify one or more *.sql files containing the source code for that objects at the “Tagged Comments” wizard screen as shown in the screen shot above. In a properly organized environment this shouldn’t represent a problem, since you keep these files in some source code managing app anyway.
To see these “Tagged Comments” in action, I’ve deliberately borrowed the following screen shot from the ApexSQL Doc online manual.
Here’s a list of the currently supported tags:
- ISNEW
- SUMMARY
- REMARKS
- RETURNS
- SEEALSO
- PARAM