• Connexion 
• Derniers changements 
•  

• [Afficher le texte source]
• [Anciennes révisions]

I am using NaturalDocs to self document the database objects (i.e. stored procedures, triggers, user defined functions and other horrors alike).

NaturalDocs is a documentation processor that create sets of web pages from comments inside the code.

It implies to respect _very few_ comment formatting rules. NaturalDocs, as its name states, is quite flexible about the way the comments are written.

Here are the basic rules to respect :

• The formatting of your comments are not respected. To go to the next line in your comment (in other words, to mimic a <BR>, create a paragraph by inserting a <b>single blank line</b>
• Use NaturalDocs keywords to separate logically parts of your comments.
• Use the Topic: keyword to add your own topics
• The keywords are case-sensitive, they should be no space between the keyword and the _:_
• Insert your comments with the appropriate keywords along your code (e.g. for variables, constants, etc.), it will be processed by NaturalDocs in order and put on a single page
• The name of the procedure <b>must be the same</b> as the Procedure: topic in the comment (notably with dbo. at both places) to allow the CREATE PROCEDURE to be processed in the documentation
• There must be no other topic between the Procedure: and the CREATE PROCEDURE code. For other topics, put it <b>between the AS and the BEGIN</b> in the procedure, use this only for specific topics you want to be indexed in the index page. For the small sections, use the headings as defined in the NaturalDocs documentation (see example below)
• If you want the index of NaturalDocs working correctly, don't put the dbo. prefix before name of objects, otherwise everything will be under the letter D. You have another solution, it is to patch yourself NaturalDocs to ignore the prefix while building the index. You can find below the procedure. It applies to NaturalDocs 1.13, that's what I've done for my own purposes.

Documentation naming rules

/******************************************
Procedure: dbo.DoSmth
 
Do Something
 
Creation:
  2002-07-21 - rudi
 
Modifications:
  2002-08-21 - rudi - read and approved
  2002-09-21 - rudi - read again
  2002-10-21 - rudi - what is that doing ?
*******************************************/
CREATE PROCEDURE dbo.DoSmth 
AS 
/*
Topic: Particular handling
*/
BEGIN
...

Patch NaturalDocs to ignore the database/owner prefixes

 sub RemovePrototypePrefix
   {
   my ($self, $prototype) = @_;
   return ($prototype =~ /\.([\w\$]+?)$/)[0];
   };

 if ((NaturalDocs::Languages::LanguageOf($definitions[0])->Name == 'SQL') && ($type == ::TOPIC_FUNCTION()))
   {
   $symbol = NaturalDocs::Languages::SQL->RemovePrototypePrefix($symbol);
   } 
 
Not safe in case of multiple definitions in different files, but ok for me.