Glossary Item Box
The power of TechWriter comes from its ability to leverage information from your database. In this topic we will show you how to document Oracle Databases by including comments directly within the database itself as an alternative to creating annotations within TechWriter. Comments can include simple text descriptions or richly formatted content depending on the comment model you wish to use.
To create table comments in an Oracle database, open the database using SQLPLUS and execute commands with the following syntax for each table you want to document:
COMMENT ON TABLE <table> IS '<comment>';
where <table> is the name of the database table and <comment> is the text of the comment you want to create.
To document columns in an Oracle database, open the database using SQLPLUS and execute commands with the following syntax for each column you want to document:
COMMENT ON COLUMN <table>.<column> IS '<comment>';
where <table> is the name of the database table, <column> is the name of the column and <comment> is the text of the comment you want to create.
View descriptions can be applied to an Oracle database the same way that table descriptions are created. Open the database using SQLPLUS and execute commands with the following syntax for each view you want to document:
COMMENT ON TABLE <view> IS '<comment>';
where <view> is the name of the database view and <comment> is the text of the comment you want to create.
TechWriter will automatically use the description for the underlying table column as a description provided the view column is not a computed column. To document the computed columns in an Oracle view, open the database using SQLPLUS and execute commands with the following syntax for each column you want to document:
COMMENT ON COLUMN <view>.<column> IS '<comment>';
where <view> is the name of the database view, <column> is the name of the column and <comment> is the text of the comment you want to create.
Oracle functions and procedures can be documented by including line comments within the body of the procedure or function definition. These comments can also include parameter descriptions using one of the supported comment models. Below is a sample procedure that includes parameter descriptions using the JavaDoc comment model:
create or replace PROCEDURE add_job_history
( p_emp_id job_history.employee_id%type
, p_start_date job_history.start_date%type
, p_end_date job_history.end_date%type
, p_job_id job_history.job_id%type
, p_department_id job_history.department_id%type
)
IS
-- Add a new job history record.
-- @param P_EMP_ID ID of the employee
-- @param P_START_DATE Starting date of employment.
-- @param P_END_DATE Last day of employment.
BEGIN
INSERT INTO job_history (employee_id, start_date, end_date,
job_id, department_id)
VALUES(p_emp_id, p_start_date, p_end_date, p_job_id, p_department_id);
END add_job_history;
In order to use comment tags for documenting query parameters and computed columns you must select the proper comment model for your database from the Database Settings dialog that is displayed when you add or edit a database for the project.
Oracle does not currently provide a method for documenting the following database objects:
However, you can still document these types of database objects using TechWriter annotations.
In some instances, you may want to format your descriptions with multiple paragraphs, lists, links and other formatting options that are available when using TechWriter's Annotation editor. While Oracle does not provide a WYSIWYG editor, you can still apply formatting to the text using the syntax defined by the comment model. TechWriter supports several different comment models, including HTML, that can be used with Oracle to format your descriptions. See Supported Comment Models for more information.
© 2005-2009 Adivo Ltd. All rights reserved.