Tags:

extract_stuff 1Add my vote for this tag stale_content 1Add my vote for this tag tag this topic 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

• CgiScripts - fulfils requests from the web. Primarily through the ViewCgiScript
• AuthenticationSubSystem - authenticates users and bestows privileges.
• ParsePipeline - interprets what's typed in forms and topics and converts into Topics, Forms, MetaData and Attachments
• StorageSubSystem - arranges for data to be stored, currently in RcsFormat
• RenderingPipeline - displays WikiML Topics, Forms, MetaData ? and Attachments as HTML
• SearchSubsystem - fulfils searches

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

• http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/twiki/twiki/bin/#dirlist

TWIKIROOT/lib

• http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/twiki/twiki/lib/#dirlist

TWIKIROOT/lib/TWiki/

• http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/twiki/twiki/lib/TWiki/#dirlist

TWIKIROOT/lib/TWiki/Plugins

• http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/twiki/twiki/lib/TWiki/Plugins/

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

• http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/twiki/twiki/lib/TWiki/Store/

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.
  • TWikiCodebaseHasNoPODDocumentation commented on this - the CoreTeam have not.
• 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月31日T19:30Z"=), ="rcs"= (e.g. ="2001年12月31日 23:59:59"=, ="http"= for HTTP header format (e.g. ="1998年7月23日 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

BasicForm
TopicClassification	TWikiDevDoc
TopicSummary	Gateway to code layout documentation for TWiki
InterestedParties
RelatedTopics	TWikiRoot, PublishCodeUsingPdoc

Topic revision: r39 - 2006年05月01日 - SamHasler