Tags:
extract_stuff1Add my vote for this tag stale_content1Add my vote for this tag create new tag
view all tags

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:

Drawing is not editable here (insufficient permission or read-only site)

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

TWikiSubSystems

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
  attach
  changes
  edit
  geturl
  installpasswd
  mailnotify
  manage
  oops
  passwd
  preview
  rdiff
  rdiffauth
  register
  rename
  save
  search
  setlib.cfg
  statistics
  testenv
  upload
  view
  viewfile
  lib
  TWiki.cfg
  TWiki.pm
  TWiki
  Access.pm
  Attach.pm
  Form.pm
  Func.pm
  Meta.pm
  Net.pm
  Plugins.pm
  Plugins
  DefaultPlugin.pm
  EmptyPlugin.pm
  Prefs.pm
  Search.pm
  Store.pm
  Store
  RcsFile.pm
  RcsLite.pm
  RcsWrap.pm
  UI.pm
  UI
  Changes.pm
  Edit.pm
  Manage.pm
  Oops.pm
  Preview.pm
  RDiff.pm
  Save.pm
  Search.pm
  Statistics.pm
  Upload.pm
  View.pm
  User.pm
  User
  HtPasswdUser.pm
  NoPasswdUser.pm

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 geturl GeturlCommandLineScript
Location TWIKIROOT/bin/geturl
Summary  
Primary Author Main.

Module name installpasswd InstallpasswdCgiScript
Location TWIKIROOT/bin/installpasswd
Summary Installs a new password for a given user. Admins only
Primary Author KlausWriessnegger

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 smile
Primary Author PeterThoeny

Module name oops OopsCgiScript
Location TWIKIROOT/bin/oops
Summary Handles when something goes wrong
Primary Author Main.

Module name passwd PasswdCgiScript
Location TWIKIROOT/bin/passwd
Summary Allows a user to change their own password. Called from ChangePassword
Primary Author AndreaSterbini

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 register RegisterCgiScript
Location TWIKIROOT/bin
Summary Used to register users. Called by TWiki. TWikiRegistration
Primary Author PeterThoeny

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 setlib.cfg SetlibDotCfg
Location TWIKIROOT/bin/setlib.cfg
Summary Determine location of the LibDirectory, relative to the BinDirectory
Primary Author Main.

Module name statistics StatisticsCgiScript
Location TWIKIROOT/bin/statistics
Summary Generates the WebStatistics page. Called by cron or via web by link on WebStatistics page
Primary Author RichardDonkin

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 view ViewCgiScript
Location TWIKIROOT/bin/view
Summary Handles viewing of Topics
Primary Author PeterThoeny

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.

Module name TWiki::Store StoreDotPm
Location TWIKIROOT/lib/TWiki/Store.pm
Summary This module implements the storage backend
Primary Author NicholasLee / JohnTalintyre

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

http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/twikiplugins/

(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 wink ) 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. wink 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 wink . 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 smile 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 smile


=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

Edit | Attach | Watch | Print version | History: r39 < r38 < r37 < r36 < r35 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r39 - 2006-05-01 - SamHasler
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.