NDlite

Extract documentation from source code.

Summary

• Introduction
  • Legal Copyright (C) 2008 Stephane Lavergne http://www.imars.com/
  • Description Useful for public and private API documentation, but also for plain text files with minimal formatting.
• Methods
  • NDlite Creates an instance of the NDlite class.
  • parseFile Load a file from disk into this instance.
  • parseString Load a source in the form of a string, into this instance.
  • guessTitle Guess the title of this instance.
  • toXHTML Produce XHTML documentation from the current source.

Introduction

Legal

Copyright (C) 2008 Stephane Lavergne http://www.imars.com/

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Description

Useful for public and private API documentation, but also for plain text files with minimal formatting. Implements a subset of the excellent www.NaturalDocs.org philosophy.

Example

$doc = new NDlite();
$doc->parseFile($path_to_my_source_file);
echo "<h1>Developer documentation for: " . $doc->guessTitle() . "</h1>\n";
echo $doc->toXHTML(array('private' => true));

TODO

• Document exactly what is supported...

Known Bugs

• I use glob() with a prefix path, part of the PATH_INFO and “.*”. In unsafe installations of PHP, I'll bet this could allow malicious users to form a PATH_INFO which could make NDlite read unintended files. For small regular files, this is mostly harmless because the chances of NDlite recognizing displayable comments is rather low. I see a possible issue with large files using all of the PHP process' allowed memory on each call. I also see an issue with devices and pipes, which could stall NDlite processes waiting for input without reaching their CPU clock limit if no wall clock limit is in force.

Future Developments

• I'd like to see a “totroff()” for creating troff output for man pages. I then could switch from POD to NDlite in my shell scripts.

• Improve plurals and possessives to match NaturalDoc's versatility.

• Add language parameter so that I can add French quote substitutions.

• Further parse function prototypes, like NaturalDocs.

Methods

NDlite

function NDlite($path = false, $URL = false)

Creates an instance of the NDlite class.

If you supply the optional path and url arguments, references to unknown symbols will cause lookups in the parsed source's current directory, then the root of the document path, for a matching basename.

Example

$doc = new NDlite("/usr/local/src/", "/cgi-bin/ndlite.cgi?q=");

As you can see, it becomes easy to use a standard query if you'd like, although I personally prefer the use of PATH_INFO to make NDlite less apparent to the end-user on a web site. If you're using NDlite for pre-processing, your URL might be simply the base of your site's output directory, like “/api-docs/” for example.

Parameters

path

Path to your documentation tree on disk. (Optional.)

URL

Base URL to reach this NDline instance. (Optional.)

parseFile

function parseFile($filename)

Load a file from disk into this instance. Internally, this is a wrapper around parseString() which calls PHP's file_get_contents() for you.

Parameters

filename

The file path to read.

Returns

The result of parseString().

parseString

function parseString($input)

Load a source in the form of a string, into this instance.

Parameters

input

The string containing source code to parse for comments.

Returns

Always true as of this version.

guessTitle

function guessTitle($fallback = false)

Guess the title of this instance. Only useful after parsing some source.

Parameters

fallback

Alternative if no suitable candidate is found. (Optional.)

Returns

The first of “File”, “Title”, “Class” or “Group” title found, or your fallback if none is found, or false if no fallback is provided.

toXHTML

function toXHTML($flags = false)

Produce XHTML documentation from the current source. It is up to your application to jazz it up with CSS as you'd like.

Parameters

flags

Named array of options. (Optional.)

Valid flags

private

Set true to include private topics, false or omit to limit display to regular topics only.

summary

Set false to explicitly request omitting the summary.

Returns

The XHTML string ready to display or save.