How to add comments to SQL CLR function? - sql

Question

I want to add comments to my SQL CLR functions (as I do to other SQL objects I am creating or editing - functions, procedures and views). Unfortunately, I am not able to do this for the SQL CLR objects.
For example, the following code:
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
-- =================================================================================================================================
-- Author: gotqn
-- Create date: 2015-03-25
-- Description: Converts a string that has been encoded for transmission in a URL into a decoded string.
-- Usage Example:
/*
SELECT [dbo].[fn_UrlDecode]('http://stackoverflow.com/search?q=tql+sql+server');
*/
-- =================================================================================================================================
CREATE FUNCTION [dbo].[fn_UrlDecode] (#value NVARCHAR(MAX))
RETURNS NVARCHAR(MAX)
AS EXTERNAL NAME [Utils].[Utils].[UrlDecode]
GO
when the function is script from the SQL Management studio is going to produce this:
SET ANSI_NULLS OFF
GO
SET QUOTED_IDENTIFIER OFF
GO
CREATE FUNCTION [dbo].[fn_UrlDecode](#value [nvarchar](max))
RETURNS [nvarchar](max) WITH EXECUTE AS CALLER
AS
EXTERNAL NAME [Utils].[Utils].[UrlDecode]
GO
I try to fix this moving the comments part after the AS as this is the way comments are added for views, but it fails again. Then I try to put the comments after the CREATE clause, after the EXTERNAL NAME ... clause, but nothing changed.
Is there a way to fix this behaviour?

Answer 1

While #Damien is correct as to why the comments are not saved, there is still a somewhat work-around to store comments: Extended Properties.
For example:
EXEC sys.sp_addextendedproperty #name = N'comments', #value = N'
-- =================================================================================================================================
-- Author: gotqn
-- Create date: 2015-03-25
-- Description: Converts a string that has been encoded for transmission in a URL into a decoded string.
-- Usage Example:
/*
SELECT [dbo].[fn_UrlDecode](''http://stackoverflow.com/search?q=tql+sql+server'');
*/
-- =================================================================================================================================
', #level0type = 'SCHEMA', #level0name = N'dbo',
#level1type = 'FUNCTION', #level1name = N'fn_UrlDecode';
You just need to escape your embedded single-quotes.
Then you can retrieve them via:
SELECT [value]
FROM sys.fn_listextendedproperty(N'comments', 'SCHEMA', N'N'dbo',
'FUNCTION', N'fn_UrlDecode', NULL, NULL);
Minor additional note: if you won't ever decode URLs that are more than 4000 characters long (and I am pretty sure that you won't run into many that are even over 2048 characters), then you would be better served to use NVARCHAR(4000) for both input and output datatypes as that will be quite a bit faster than if either, or both, are NVARCHAR(MAX).

Answer 2

Basically, if it's a type not listed as having data stored in sys.sql_modules then the original text that created the object is not retained and so comments aren't retained. No CLR object stores such text.

Answer 3

This is the expected behavior. Even when you write a native TSQL script adding comments right before the routine signature, build it against the DBMS and do right click/edit to see the code the comments won't be there. Go ahead and give a try to this approach:
CREATE FUNCTION [dbo].[fn_UrlDecode]
(
#value [nvarchar](max)
)
RETURNS [nvarchar](max) WITH EXECUTE AS CALLER
AS
/*
***All the comments goes here***
*/
EXTERNAL NAME [Utils].[Utils].[UrlDecode]
GO
Hope it helps!

Answer 4

Committing Necromancy.
Solution first...reason second...
Simply wrap the CLR function in a standard function and put the comments in the standard function.
Overkill? Perhaps, but as I said, I have a reason and need in my current situation.
As an employee of a contractor to a large organization, there are tons of fingers in every pie, and the hands attached to those fingers are usually long gone and forgotten...but maintenance of their legacy code lives on. This is especially noticeable when external assemblies are loaded in a database, and there is a need to change or augment existing libraries...somewhere...but where. The coder is gone, and the documentation of the process is buried somewhere long forgotten.
So, for me, the primary reason for commenting such functions is to make it easy to identify the name of the Assembly and the Repository for the Source Code. Other than starting out with properly documented code in the first place (remember this is legacy cruft) I am open to other suggestions about better places/ways to do this...I am all ears.
Providing this information in a comment, somewhere in or related to the function or assembly, is very helpful. The simple wrapper noted above is a very KISS method to achieve this goal.