Documentation for Code Structure Format (CSF2) DTD

Version:	0.5x
Creator:	Stig E Sandų
PublicId:	`-//SDS//CSF DTD 0.5x//EN`

Description

The CSF DTD is used to represent information about Code Structure. The format is not really meant to be written by humans, but should be output by various tools. The format is also pretty raw and as-is will require some effort by the tool which uses the information from a CSF document. It is suggested that you tailour a DTD for your need and make a conversion tool from CSF to your format. This has been done for SDS-documentation (SDOC)

Root elements

Element index

access	Describes access
arg	Describes a method-argument/parameter
class	Describes a class
comment	Describes a comment
csf	The root element.
directive	A special directive
enum	Describes an enum
enumval	Describes an enum value
info	Context-specific placeholder for info
inherit	Describes what is inherited
location	Describes a location
method	Describes a method
package	Describes a package
retval	Describes a method's return value
text	contains text
typespec	Describes a typedef/typespecification
variable	Describes a variable
where	Describes the whereabouts of a function

Attribute index

endcol on location
endline on location
file on location
id on class
id on enum
id on method
id on package
id on typespec
id on variable
info on directive
info on info
language on csf
name on class
name on directive
name on enum
name on enumval
name on inherit
name on method
name on package
name on typespec
name on variable
position on location
scope on access
startcol on location
startline on location
type on info
value on directive
value on enumval
value on info
visibility on access
what on where

Element descriptions

access

Describes access The access element contains information about how some object may be accessed (in class or file).

Parents

class enum method typespec variable

Content model

EMPTY

Attributes

Name	Type	Declaration	Default	Description
scope	CDATA	#DEFAULT		The scope can be class, file, function, ...
visibility	CDATA	#DEFAULT		Whether we have public, protected, private, package (Java) or global visibility. Please use public and not global for anything in a class, e.g an accessor in a CLOS class is public.

arg

Describes a method-argument/parameter The arg element contains information about a parameter or argument to a method. This is done through the info-elements which are described in the CSF specification.

Parents

method

Content model

(info*)

class

Describes a class The class element contains information about a class and it's content. It contains some C++isms but is somewhat general.

Parents

class csf method package

Content model

Attributes

Name	Type	Declaration	Default	Description
id	CDATA	#REQUIRED		An id to refer to
name	CDATA	#IMPLIED		The name

comment

Describes a comment The comment element contains information about a comment in code and includes the location and the text. This element is basically included for systems getting extra information from comments.

Parents

class csf method package

Content model

(location , text)

csf

The root element. The csf element is just the root element of the DTD and it's only significance is the lang attribute.

Parents

Must appear as the root element.

Content model

Attributes

Name	Type	Declaration	Default	Description
language	CDATA	#DEFAULT		Names the language the CSF-data is generated from. This information may be used e.g by the linker who e.g will probably refuse to link together lisp and c++ code.

directive

A special directive The directive element is used for various directives found in code and which should be included. Examples are #include, #define and #pragma in C/C+. Refer to the spec.

Parents

class csf method package

Content model

(location)

Attributes

Name	Type	Declaration	Description
info	CDATA	#DEFAULT	extra info.
name	CDATA	#DEFAULT	the name/type of directive.
value	CDATA	#DEFAULT	the value of the directive.

enum

Describes an enum The enum element contains information about an enum object and it's values. C/C++ style.

Parents

class csf method package

Content model

(location , access , enumval*)

Attributes

Name	Type	Declaration	Default	Description
id	CDATA	#REQUIRED		An id to refer to
name	CDATA	#DEFAULT		The name

enumval

Describes an enum value The enumval element contains information about a value which is part of an enum. C/C++ style.

Parents

enum

Content model

EMPTY

Attributes

Name	Type	Declaration	Default	Description
name	CDATA	#DEFAULT		The name
value	CDATA	#DEFAULT		A specified value

info

Context-specific placeholder for info The info element is a place holder for info. what the info means depends on where it is used and the CSF Specification is a good place to start searching for that info.

Parents

arg class inherit method package retval typespec variable

Content model

EMPTY

Attributes

Name	Type	Declaration	Description
info	CDATA	#IMPLIED	extra info.
type	CDATA	#IMPLIED	what type of info object it is.
value	CDATA	#IMPLIED	the value of the type.

inherit

Describes what is inherited The inherit element contains information about what a class inherits, mostly through the info-fields.

Parents

class

Content model

(info*)

Attributes

Name	Type	Declaration	Default	Description
name	CDATA	#DEFAULT		The name of the other class/object inherited

location

Describes a location The location element contains information about the location of some object in a file. It is line/column based.

Parents

class comment directive enum package typespec variable where

Content model

EMPTY

Attributes

Name	Type	Declaration	Default	Description
endcol	CDATA	#DEFAULT	-1	The end column
endline	CDATA	#DEFAULT	-1	The end line
file	CDATA	#DEFAULT		The name of the file
position	CDATA	#DEFAULT	-1	The absolute position in the file
startcol	CDATA	#DEFAULT	-1	The start column
startline	CDATA	#DEFAULT	-1	The start line

method

Describes a method The method element contains information about a method and it's content. It contains some C++isms but is somewhat general.

Parents

class csf method package

Content model

Attributes

Name	Type	Declaration	Default	Description
id	CDATA	#REQUIRED		An id to refer to
name	CDATA	#DEFAULT		The name

package

Describes a package The package element contains information about a package object and it's content. It's mostly equal to a package in Java or Common Lisp.

Parents

class csf method package

Content model

Attributes

Name	Type	Declaration	Default	Description
id	CDATA	#REQUIRED		An id to refer to
name	CDATA	#IMPLIED		The name

retval

Describes a method's return value The retval element contains information about a method's return value. This is done through the info-elements which are described in the CSF specification.

Parents

method

Content model

(info*)

text

contains text The text element contains text for a comment.. normal #PCDATA basically.

Parents

comment

Content model

(#PCDATA)

typespec

Describes a typedef/typespecification The typespec element contains information about a typedef or type-alias object and it's content. The info-fields are described in the specification.

Parents

class csf method package

Content model

(location , access , info*)

Attributes

Name	Type	Declaration	Default	Description
id	CDATA	#REQUIRED		An id to refer to
name	CDATA	#REQUIRED		The name

variable

Describes a variable The variable element contains information about a variable object and it's content. This is a feature found in most languages.

Parents

class csf method package

Content model

(location , access , info*)

Attributes

Name	Type	Declaration	Default	Description
id	CDATA	#REQUIRED		An id to refer to
name	CDATA	#DEFAULT		The name

where

Describes the whereabouts of a function The where element contains information about where a method was found and what kind of method-info was found there (e.g declaration, definition, etc).

Parents

method

Content model

(location)

Attributes

Name	Type	Declaration	Default	Description
what	['declaration', 'definition', 'unknown']	#DEFAULT	unknown	what describes what kind of method-info was found. It can be declaration, definition or unknown where the default is unknown.

Produced by dtddoc.py, using xmlproc.