Developer Documentation
Purpose
This topic is the gateway for Codev topics documenting the layout of the TWiki codebase. It is important to note that many internal details are specified that are
not guaranteed to remain the same in future TWiki versions. The only thing the TWiki developers will attempt to maintain invariant is the behavior of
FuncDotPm. If you're writing "external" code such as Plugins that must interface with TWiki, please try and stick to the documented
FuncDotPm interface as much as you can. It is possible to use any other bits of intenal TWiki implementation you want, but be aware that if they change or are removed in a new version it will be your obligation to figure out how to reimplement your code to work with the new version. --
WalterMundt 01 Feb 2004
Original proposal:
I propose that we share the task and collectively document the code outline.
- I invite you, the reader, to help by creating and/or editing the topics for each of the modules. I have this for some of the modules, e.g. TWikiDotPm and FormDotPm but its more work than I'm prepared to do by myself.
- I propose that, once sufficiently useful, we link to this topic from AppendixFileSystem
- I also propose that each file in CVS have a reference back to this topic and to the topic specific to that file.
Overview of code modules used in TWiki:
See other
ArchitectureDiagrams
Goals
- to document such that interested parties can progressively dig deeper such that the first step gives a visual picture of how TWiki is put together and that each subsequent step allows them to dig deeper.
- to document in such a way as to keep to bare minimum the duplication between the code base and the documentation.
- to document the degree of coupling and cohesion in the code. If necessary, reduce coupling and cohesion by making more of the methods private to the modules.
Comments welcome at:
CodevDocumentationProjectDev
The
TWikiCore is comprised of several subsystems (the following list is
not complete)
TWiki SubSystems
Files in the distribution
BTW: The template is at CodevDocumentationProjectTemplate, use that to create any missing docs. Make sure the parent is this topic
Overview
TWIKIROOT/bin
Module name |
attach AttachCgiScript |
Location |
TWikiRoot/bin/attach |
Summary |
Provides functionality to update or create an attachment to a page |
Primary Author |
Main. |
Module name |
changes ChangesCgiScript |
Location |
TWIKIROOT/bin/changes |
Summary |
Presents to user recent changes made to the current web |
Primary Author |
NicholasLee |
Module name |
edit EditCgiScript |
Location |
TWIKIROOT/bin |
Summary |
|
Primary Author |
Main. |
Module name |
mailnotify MailnotifyCgiScript |
Location |
TWIKIROOT/bin/mailnotify |
Summary |
Produces periodic notifications based on whether people have added themselves to WebNotify |
Primary Author |
NicholasLee |
Module name |
manage ManageCgiScript |
Location |
TWIKIROOT/bin/manage |
Summary |
tools to manage the twiki using the twiki |
Primary Author |
PeterThoeny |
Module name |
oops OopsCgiScript |
Location |
TWIKIROOT/bin/oops |
Summary |
Handles when something goes wrong |
Primary Author |
Main. |
Module name |
preview PreviewCgiScript |
Location |
TWIKIROOT/bin/preview |
Summary |
|
Primary Author |
Main. |
Module name |
rdiff RdiffCgiScript |
Location |
TWIKIROOT/bin/rdiff |
Summary |
To present a view of differences between revisions of topics |
Primary Author |
Main. |
Module name |
rename RenameCgiScript |
Location |
TWIKIROOT/bin/rename |
Summary |
Functionality to rename a topic |
Primary Author |
PeterThoeny |
Module name |
save SaveCgiScript |
Location |
TWIKIROOT/bin/save |
Summary |
When user saves changes, this writes changes to the data store |
Primary Author |
PeterThoeny |
Module name |
search SearchCgiScript |
Location |
TWIKIROOT/bin/search |
Summary |
To return HTML that represents result of a %SEARCH directive |
Primary Author |
Main. |
Module name |
testenv TestenvCgiScript |
Location |
TWIKIROOT/bin/testenv |
Summary |
|
Primary Author |
Main. |
Module name |
upload UploadCgiScript |
Location |
TWIKIROOT/bin/upload |
Summary |
Used to implement the uploading of attachments |
Primary Author |
NicholasLee |
Module name |
viewfile ViewfileCgiScript |
Location |
TWIKIROOT/bin/viewfile |
Summary |
Presents contents of previous versions of attachments |
Primary Author |
NicolasLee |
TWIKIROOT/lib
Module name |
TWiki TWikiDotPm |
Location |
TWIKIROOT/lib/TWiki.pm |
Summary |
Single include library for CgiScripts containing a mishmash of functions |
Primary Author |
PeterThoeny |
Module name |
TWikiDotCfg |
Location |
TWIKIROOT/lib/TWiki/ |
Summary |
TWiki configuration file |
Primary Author |
PeterThoeny |
TWIKIROOT/lib/TWiki/
Module name |
TWiki::Access AccessDotPm |
Location |
TWIKIROOT/lib/TWiki/Access.pm |
Summary |
To provide access checking |
Primary Author |
PeterThoeny |
Module name |
TWiki::Access AttachDotPm |
Location |
TWIKIROOT/lib/TWiki/Attach.pm |
Summary |
File attachment functionality |
Primary Author |
PeterThoeny |
Module name |
TWiki::Form.pm FormDotPm |
Location |
TWIKIROOT/lib/TWiki/Form.pm |
Summary |
Handle the encoding and decoding of the TWikiForms presented at the bottom of each page |
Primary Author |
JohnTalintyre |
Module name |
TWiki::Func.pm FuncDotPm |
Location |
TWIKIROOT/lib/TWiki/Func.pm |
Summary |
Stable interface from Plugins to TWiki |
Primary Author |
PeterThoeny |
Module name |
TWiki::Meta MetaDotPm |
Location |
TWIKIROOT/lib/TWiki/Meta.pm |
Summary |
Implements the meta data handling |
Primary Author |
Main. |
Module Name |
TWiki::Net, NetDotPm |
Location |
TWIKIROOT/lib/TWiki/Net.pm |
Summary |
This module handles network related functions like http access and send mail |
Primary Author |
Main. |
Module name |
TWiki::Plugins PluginsDotPm |
Location |
TWIKIROOT/lib/TWiki/Plugins.pm |
Summary |
this is the plugin discoverer, loader and runner |
Primary Author |
AndreaSterbini |
Module name |
TWiki::Prefs.pm PrefsDotPm |
Location |
TWIKIROOT/lib/TWiki/Prefs.pm |
Summary |
TWiki preferences handling on site-level, web-level and user-level |
Primary Author |
PeterThoeny |
Module name |
TWiki::Search SearchDotPm |
Location |
TWIKIROOT/lib/TWiki/Search.pm |
Summary |
This module implements all the search functionality |
Primary Author |
Main. |
TWIKIROOT/lib/TWiki/Plugins
Module name |
TWiki::Plugins::Default DefaultPluginDotPm |
Location |
TWIKIROOT/lib/TWiki/Plugins/Default.pm |
Summary |
|
Primary Author |
Main. |
Module name |
TWiki::Plugin::Empty EmptyPluginDotPm |
Location |
TWIKIROOT/lib/TWiki/Plugins/Empty.pm |
Summary |
|
Primary Author |
Main. |
Warning: Can't find topic Codev.InterwikiPluginDotPm
(This area is (23/Jun/2003) currently unused)
TWIKIROOT/lib/Store
Module name |
TWiki::Store::RcsFile RcsFileDotPm |
Location |
TWIKIROOT/lib/TWiki/Store/RcsFile.pm |
Summary |
|
Primary Author |
Main. |
Module name |
TWiki::Store::RcsLite.pm RcsLiteDotPm |
Location |
TWIKIROOT/lib/TWiki/Store/RcsLite.pm |
Summary |
|
Primary Author |
Main. |
Module name |
TWiki::Store::RcsWrap RcsWrapDotPm |
Location |
TWIKIROOT/lib/TWiki/Store/RcsWrap.pm |
Summary |
|
Primary Author |
Main. |
TWIKIROOT/pub
TWIKIROOT/data
--
MartinCleaver - 23 Jun 2002
One thing I have found helpful in code documentation within twiki (not of twiki itself but of company code) is a custom plugin ... (Discussion refactored to
FilenamePlugin by
MartinCleaver)
--
JonathanCline - 07 Jul 2002
TWiki source code published on web
I used Pdoc
http://pdoc.sourceforge.net/ to publish source code of Twiki /lib. You can see it
here. My comments:
- I found way to publish only
.pm
modules. From .pl programs in /bin, only testenv worked - seehere. I am at lost why.
- Pdoc expects POD docs, and specially formatted POD sections before each
sub
. Because Twiki code (currently ) does not adhere, big chunks of docs are missing (which will be present at correctly documented packages, see here docs in bioperl website.
- Published version is Alpha 03 May 2003
--
PeterMasiar - 16 May 2003
This is wonderful Peter, thankyou.
One suggestion: As much as I think we should
MoveTWikiDotOrgOffSourceForge, it is useful to have all twiki stuff on the same server. So, can I suggest that you register as a
PluginsCoreTeam member, and then use the cgi-bin at
http://twikiplugins.sourceforge.net/ to host this code? Perhaps under cgi-bin/pdoc?
That way the other contributors can make changes/upgrades should you not be able or wanting to.
I say this after having previously hosted TWiki adjunct projects on my servers (at
TWikiFileDependencies) but broke them when I moved them for other reasons. As such, the functionality that I had provided now fails.
--
MartinCleaver - 17 May 2003
Pdoc looks nice, and it would be good if the TWiki code had some docs in POD format. I'd want to get all the TWiki scripts displayed by Pdoc before hosting it at twikiplugins, though - something to raise with the Pdoc authors perhaps.
I have been putting comments in various modules over the time I've been in the
CoreTeam, at the function and paragraph level. If the rest of the
CoreTeam agree that POD or perhaps Pdoc-enhanced POD are a good idea (I like the idea of standardised function input/output comments as in Pdoc, but I don't know if everyone would), I'd be OK with converting these into the new format, though I am not volunteering to do all of this since it's a lot of work! Perhaps we need a new
CoreTeam member who will sign up to do this - as always, it's fine to request better docs but someone has to actually write them, and familiarity with the code is important no matter how good the docs are.
--
RichardDonkin - 17 May 2003
We use Pdoc internally, so all I did was to run it for TWiki Alpha source code what I am installing. Thank you Martin for considering me a
PluginsCoreTeam material.
My interests are not in developing plugins, but making better default distribution (from existing stable plugins). I am not sure how I am going to distribute it yet.
--
PeterMasiar - 17 May 2003
If
CoreTeam is interested, I can take over Pdoc, install it etc. Pdoc is perl, so we can even implement Twiki markup if we want to
. That's the key - does
CoreTeam want to use Pdoc for documentation?
--
PeterMasiar - 17 Jul 2003
I think it would be a good idea to start documenting the TWiki code with Perl's built-in documentation format, POD. I need to look through the code to refamiliarize myself with how it's set up, so I'm going to start writing up POD entries and committing them to CVS as I read the functions. I encourage the rest of the
CoreTeam and any others who are familiar with the code base to help out and correct my errors. I'll start with TWiki.pm, so if anyone wants to make a parallel effort I suggest they pick one of the subsidiary modules under the
TWiki/
subdirectory.
--
WalterMundt - 29 Jan 2004
Walter, I concur - but i don't know anything about POD
I'll do the User.pm /
HtPasswdUser.pm stuff when i learn
--
SvenDowideit - 29 Jan 2004
Func.pm
has a bunch of pod-looking stuff in it.
--
MattWilkie - 29 Jan 2004
Yeah, looks like
Func.pm
is already set up with pod. However, I've taken a bit of a less formal tack with documenting the rest of the code. Since it's not part of a static API, the very explicit format of the Func.pm stuff might be a bit of overkill. Too much detail in documentation of this sort is difficult to maintain; a concise summary of what the function does and, if absolutely necessary, where it's used should be sufficient. Also, the pod in Func.pm is all done up with TWiki markup. I suggest that it'd be better to use POD's native formatting where it applies. Look at the stuff I've just committed for examples. Also, the perlpod manpage has an overview of the formatting elements available...look at that if what I've used doesn't give you enough.
--
WalterMundt - 29 Jan 2004
Pod allows extensions, e.g. you can switch to a different syntax with a
=begin anyname
line. The
TWiki::Func
module uses
=begin twiki
to indicate TWiki syntax. The
PerlDocPlugin can show standard pod docs and twiki pod docs of Perl modules installed on the server, simply enter the module name like
Date::Calc
or
TWiki::Func
.
Here is an extract of the TWiki/Func.pm file showing the doc of just one function:
# =========================
=pod
---++ Functions: CGI Environment
---+++ getSessionValue( $key ) ==> $value
| Description: | Get a session value from the Session Plugin (if installed) |
| Parameter: =$key= | Session key |
| Return: =$value= | Value associated with key; empty string if not set; undef if session plugin is not installed |
=cut
# -------------------------
sub getSessionValue
{
# my( $theKey ) = @_;
return &TWiki::getSessionValue( @_ );
}
I recommend to use the twiki pod format since it is much easier to read by us TWiki developers then the cryptic native pod format. In addition anyone can see the latest module doc of the TWiki installed on the system (which changes frequently here on TWiki.org). That is, each module topic (
FuncDotPm,
MetaDotPm, etc) can pull the live pod docs from the currently installed module. I have done that for the
FuncDotPm module.
As Walter said, we do not need to follow the formal doc style of the TWiki::Func module (which gets copied as static TWiki text into the
TWikiFuncModule topic in production releases); a simple summary on top and/or some interspersed comments in pod (preferrably in twiki pod format) is fine.
--
PeterThoeny - 29 Jan 2004
I guess I see your point re: the different POD syntaxes. The only concern with this approach that I considered was that it may make the documentation somewhat less accessible to developers who are new to TWiki, but familiar with Perl and POD. However, given the overall simplicity of TWiki markup and the fact that such developers would have to learn it before trying to write patches for core TWiki code, it's really not an issue.
I actually like the POD header syntax better, personally.
=headN feels more "transparent" to me than
---++
. However, a simple search and replace will switch between the two, so this is also not really an issue. For now I'll start using the TWiki style throughout, though. I'll commit a change sometime today that switches the stuff I've already written over.
--
WalterMundt - 29 Jan 2004
POD template to be used in perl code
to make sure that we all use the same keywords, and consider some that we otherwise may forget - you can copy the following when you docco something
=pod
---+++ formatTime( $time, $format, $timezone ) ==> $text
| Description: | Format the time int seconds into the desired time string |
| Parameter: =$time= | Time in epoc seconds |
| Parameter: =$format= | Format type, optional. Default e.g. ="31 Dec 2002 - 19:30"=, can be ="iso"= (e.g. ="2002-12-31T19:30Z"=), ="rcs"= (e.g. ="2001/12/31 23:59:59"=, ="http"= for HTTP header format (e.g. ="Thu, 23 Jul 1998 07:21:56 GMT"=) |
| Parameter: =$timezone= | either not defined (uses the displaytime setting), "gmtime", or "servertime" |
| Return: =$text= | Formatted time string |
| Note: | if you used the removed formatGmTime, add a third parameter "gmtime" |
| TODO: | this function needs help :) |
| Since: | TWiki::Plugins::VERSION 1.000 (26 Feb 2004) |
=cut
Field |
Description |
Description: |
|
Parameter: $var |
the parameters to the perl function. please also document the CGI::param()'s if there are any (like all CgiScripts) |
Return: $return |
description of return and type |
Note: |
extra info |
TODO: |
please do this |
Since: |
indicates $TWiki::Plugins::VERSION and date at which the function was added |
Make sure to leave an empty line after
=pot
and before
=cut
, the pod interpreter expects that.
--
SvenDowideit - 24 Mar 2004
I took out the dash comments at top and bottom. While
PerlDocPlugin can deal with these, the POD language spec specifies a blank line before and after every POD statement is required. Specifically, if you have a comment immediately preceding the =pod line, standard POD parsers (like the
podselect(1) command in the Perl distribution) won't recognize the POD block at all.
--
WalterMundt
http://twikiplugins.sourceforge.net/pdoc/ - i will open up a new ticket to
PublishCodeUsingPdoc
--
WillNorris - 26 Jan 2005
See
CodingStandards for the POD docs used with DEVELOP code.
DevelopBranch code docs are all standardised.
Personally I think we should ditch POD - after all, we are not really using it, we are embedding TWiki text - and instead focus on extracting more doc from the code, instead of relying on banner comments. The method spec can be derived directly from the code, in the same way as javadoc or oxygen - altogether
mush easier to use/read.
--
CrawfordCurrie - 18 Feb 2005
Crawford started to mark some of the cgi script docs for deletion, such as the
RdiffCgiScript. The file documentation topics are totally out of date, and are hard to maintain in sync with the latest release, so removing those is probably a sensible thing. Rather than editing every topic (and spamming
WebChanges and
WebRss) it might be easier to list the topics to delete here (each topics
needs to be looked at if there is useful content and if they are referenced from elsewhere), than to delete them after a review.
CrawfordCurrie
09 Mar 2006 - 17:18 - r1.5
CategoryStale De
--
PeterThoeny - 09 Mar 2006