xjDocs Help

Copyright © 2003–2014
Park Bench Software, LLC
All Rights Reserved
Disclaimer
This software is provided “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall anyone (specifically Park Bench Software, or its employees) be liable for any direct, indirect, incidental or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and arising in any way out of the use of this software.
Alpha Warning
Please note - xjDocs is currently in an “Alpha” release. This means that there are parts that are not necessarily complete or properly functioning, how things operate may change before the final release, error reporting is mostly non-informative, and the documentation is sparse. Be prepared for any problems, and please help by reporting any issues.
Please review the alpha limitations listed on our website: http://www.parkbenchsoftware.com/xjDocs/
Basic Concepts
xjDocs scans Xojo projects (“sources”) and keeps a database of the contents of all the projects you want to document. In your projects, you include specially marked code comments, and specially named notes that contain the actual documentation. As your projects are updated, xjDocs will determine the changes, and allow you to apply those same changes to the information stored in the database.
You will create “Documentation Sets”, which each contain specifically chosen items from a source (or multiple sources), and different options for the generated documentation. Based on the chosen options, xjDocs will generate HTML output based on a customizable template system.
Filters can be used to aid in selecting items to document based on a set of qualifiers.
Within your documentation, xjDocs has the option to use MultiMarkdown, a superset of Markdown.
Quick Start Walkthrough
While following this walkthrough, you may want to use the included example Xojo project (“xjDocs Example Source”), as it has some examples of the documentation comments and notes in it.
First Launch
On first launch of the application, you will be prompted to create a new database (or locate one, if the location of your existing database is unknown)
New Database
After creating a new database, xjDocs will start by offering to add your first source (Xojo project file), with options to scan and load the contents, and create a documentation set to go along with it.
Adding a Source

If you leave the options as is, and continue (as you should) you will be asked to choose a Xojo project file.
Updating Changes
After selecting the project file, you will be presented with a list of items that were found in the project, and the option to load (“update”) them (which you should).

After adding the items from the source, if you chose the option to “Create a matching documentation set”, one will be created and populated with all the items from the source.
New Documentation Set

Documentation Set Contents
While viewing the documentation set, if you select the source from the list shown in the details on the right, and click “Edit”, you can see the items that were selected, and add or remove from this selection. Only items selected will be included in the documentation.

If you are following along with the sample project, you can choose the “Use MultiMarkdown” option to see some formatting options (or keep the option off to see things unformatted)
Click “Build and Preview” to see some documentation.
Documentation Format
Within your Xojo projects, you will be creating the documentation that goes along with basic project items (Classes, Interfaces, Modules, Windows, Container Controls) and the things they contain (Methods, Properties, Constants, Enums, Structures, etc.)
For items that have a place to enter comments (Methods, Properties, etc.), you will use a special comment “marker” to let xjDocs know these comments should be used in that item’s documentation.
That marker can take one of two forms:
']
or
//]
(in other words, either a single quote or two slashes, followed by a right square bracket, and you may include spaces before the right bracket)
Note: The first space after the right-square bracket will be removed.
An example documented method:
Sub PublicMethod()
'] This method does all kinds of wonderful things
//] No, really, it does
// ] I'm not sure why I need so much space, but since I can...
while not done
DoWonderfulThings()
wend
End Sub
There are two special additions for method-like items, to specifically document parameters and return values.
For parameters, the format is as follows:
'] param:: parameterName, parameterDescription
Where parameterName is the name of the parameter, and parameterDescription is the description / comments for that parameter
For return value, the format is as follows:
'] return:: returnDescription
Where returnDescription is the description / comments for the return value
A sample method using these items:
Function GetStringFromObject(inObject as Object, inMaxLength as integer) as string
'] This function claims to turn an object into a string,
'] but honestly, I wouldn't trust it
']
'] param:: inObject, the object to turn into a string
'] param:: inMaxLength, the maximum length of the string to create
']
'] return:: a string representation of the object
Return "Yes, I ignored all input and returned a canned string..."
End Function
To document top level project items (Classes, Interfaces, Modules, etc.) as well as things that do not have a place to enter comments (Event Definitions, Constants, Structures, etc.) you will need to create a note with a special name.
For top level items (Classes, Interfaces, Modules, etc.), the note name is just a right square bracket alone:
]
For other items, the name starts with a right square bracket, a space, a special tag, then the name of the item.
For example, a note for an event definition named “ThingsHappened” would be named like this:
] ED:ThingsHappened
The full list of the items and their tags is as follows:
Item | Tag |
---|---|
Constants | C: |
Computed Properties | CP: |
Delegates | D: |
Event Definitions | ED: |
External Methods | EM: |
Enums | EN: |
Methods | M: |
Menu Handlers | MH: |
Properties | P: |
Structures | S: |
Shared Computed Properties | SCP: |
Shared Methods | SM: |
Shared Properties | SP: |
(Note: even things that can contain comments can use the note as an alternative)
Special Cases
Overloaded Methods
Overloaded methods are a special case, since they have the same name, hence the same note. While it would be easiest just to include the comments in each version of the method, xjDocs provides the ability to use a note, and split that note up for each version of the method. Within the note for the method(s), special tags are used to determine which parts go with which versions. Here is an example note for an overloaded method:
Here at the beginning of the note is some information that applies to all the versions of the method
[XJD:()]
This part applies to the version of the method with no parameters
[XJD:(boolean)]
This part applies to the version of the method with one boolean parameter
[XJD:(boolean,integer)]
This part applies to the version of the method with one boolean and one integer parameter (in that order)
Enums and Structures
In order to include details about specific components of an enum or structure, the note for that enum / structure can be split using special tags. Anything before a tag will be part of the documentation for the whole enum / structure, while anything with a tag that matches the name of the individual component can show its information (based on how the current template handles that display)
The special tag looks like this:
[XJD:COMPONENT:componentName]
where componentName is the name of the specific enum / structure component.
For example, a note for an enum with components item1, item2, and item3 could look like this:
This text describes the enum itself
[XJD:COMPONENT:item1]
This text describes the item1 component of the enum
[XJD:COMPONENT:item2]
This text describes the item2 component of the enum
[XJD:COMPONENT:item3]
This text describes the item3 component of the enum
Note Sections
Notes can be split up into sections using special tags, and templates can be designed that layout these sections in different ways.
The tag for splitting a note into sections looks like this:
[XJD:SECTION:sectionName]
where sectionName is a name that is known and used by the current template.
Text before any section tag will show up where the template doesn’t specify a section. Text in a section with a name the template doesn’t use, won’t show up at all.
In the default template, top level items (Classes, Interfaces, Modules, Windows, Container Controls) have a section called “DETAILS” that shows up at the end of the documentation for the item. An example note for a Class using the DETAILS section would look like this:
This text will show up at the top of the class documentation
[XJD:SECTION:DETAILS]
This text will show up at the end of the class documentation (because the template is designed to do that)
[XJD:SECTION:WALRUS]
This text will not show up at all, since the template does not implement a section named "WALRUS"
The xjd_Info Module
In each Xojo project that you will be documenting, you will want to create a module called:
xjd_Info
This special module will hold some extra documentation for the project as a whole. Within this module, you will create notes that go along with special items in the template you are using. Templates can use as many notes as they want, with whatever names they want, with the restriction that they should not start the note names with “xjd_”. Notes starting with “xjd_” are reserved for special use.
The default template uses 2 notes inside the xjd_Info module:
“MainDescription” - is displayed as the first thing on the main page for the documentation
“Summary” - is displayed on the main index page of a multi-source documentation set
Special xjd_ Notes
Currently there is only one special note:
“xjd_Fields” - this note contains any number of short (single line or less), unformatted strings that the template can access with special tags
Each field needs to be on a single line in the note, with the following format:
fieldName = fieldContents
where fieldName is the name of the field (as expected by the template), and fieldContents is the contents of the field, as it will be displayed.
The default template uses 2 fields:
“Main_Title” - the HTML title of the main page
“SubPage_Title_Prefix” - a prefix added to the name of the current item being viewed to make up the HTML title of the other pages
The example project uses the following in the xjd_Fields note of the xjd_Info module to implement these fields:
Main_Title = xjDocs Example
SubPage_Title_Prefix = xjDE