Re: Documentation system
by jplindstrom (Monsignor) on Oct 08, 2004 at 16:29 UTC
|
Take a look at Mark Overmeer's OODoc and see if that fits the bill. There are examples.
/J
| [reply] [Watch: Dir/Any] |
|
Thanks, this looks quite perfect! I will definitely give it a try.
| [reply] [Watch: Dir/Any] |
Re: Documentation system
by kutsu (Priest) on Oct 08, 2004 at 16:11 UTC
|
Preferred method of documentation? covered a lot of documentation ideas, both systems and methods, you might look there for ideas.
"Cogito cogito ergo cogito sum - I think that I think, therefore I think that I am." Ambrose Bierce
| [reply] [Watch: Dir/Any] |
Re: Documentation system
by SpanishInquisition (Pilgrim) on Oct 08, 2004 at 17:58 UTC
|
I am currently working on my diploma thesis, written in Perl of course ;-).
That made a funny picture in my head...
sub make_thesis {
my $thesis = new Thesis(
reference => [ new Bose::Einstein, new Quantum::Entanglement(),
+new Matter::Dark ],
proposed => new BackOf::GiantTurtle(),
);
$thesis->prove();
# $thesis->ambigious_filler_with_big_words();
# $thesis->make_sound_important();
$thesis->lots_of_graphs();
$thesis->conclusion();
$thesis->bibliography();
return $ITS_ALL_GOOD;
}
| [reply] [Watch: Dir/Any] [d/l] |
|
That made my day :-). Actually, writing my thesis was as easy as that. The hard part was to write Thesis.pm, since I couldn't find it on CPAN ;-).
Joke aside, of course I meant I wrote the software for my diploma project in Perl (using wxPerl). The thesis itself is written in a mixture of German and LaTeX. As soon as I have finished off various things, I'll probably write a meditation about it.
| [reply] [Watch: Dir/Any] |
Re: Documentation system
by slagel (Novice) on Oct 08, 2004 at 16:04 UTC
|
I've always had the same desire, POD just doesn't do enough
for me and I've always been jealous of the clean way java
does it with javadoc. We just ended up writing our own script to do this, maybe I'll get it posted so others can use it.
I've heard somewhere out there their is a script that will
allow you to use doxygen with perl, I don't remember the link but I think you can find it from the doxygen web site.
Another tool you might want to look at is pdoc.
| [reply] [Watch: Dir/Any] |
Re: Documentation system
by jimbojones (Friar) on Oct 08, 2004 at 16:28 UTC
|
Hi
One cheesy thing that you could do is to use Doxygen by putting all the Doxygen comments after an __END__.
#-- Perl script
print "Test Perl Script\n";
__END__
/*! \class Test
\brief A test class.
A more detailed class description.
*/
You'd have to use the "Documentation at other places" format and you'd wouldn't get any of the source scanning features.
The other problem is that the .pl extension isn't recognized. You'd either have to work on the Doxygen source, or write a wrapper script that linked your .pm files to a recognized extension. This hack creates problems in the doc itself, because it says things like
was generated from the following file:
* test2.cpp
instead of
* test2.pm
Also, based on some of the other posts, it appears there is a Perl-to-Doxygen script call DoxyFilt. However, I couldn't connect to that site. It appears to read the POD and parse the module to create pseudo-C files with the Doxygen comments.
- jim | [reply] [Watch: Dir/Any] [d/l] [select] |
|
After some googlification, I got a link to access all the files of DoxyFilt :
ftp://ftp.doorways.org/doxyfilt
Seems like the project is not maintained anymore though.
- G.
| [reply] [Watch: Dir/Any] |
|
There is a somewhat recent version (a few months old), and after fixing two typos, it works rather well for me. I think I prefer this to OODoc, actually.
| [reply] [Watch: Dir/Any] |
Documentation system -- Important note on OODoc
by crenz (Priest) on Oct 12, 2004 at 17:09 UTC
|
A quick update in-between: I tried out OODoc, but I'm not sure whether it fits the bill. It's very module-oriented; I couldn't get it to include docs from my .pl files. I want to document the whole project, not just the classes. Still, I'll try to take further looks at it.
I have an important warning, though: OODoc can delete your files if you are not careful. The example given in the manpage will filter your source and replace the files with files without documentation. When I used that example, it replaced all my files with empty files :-( . Fortunately, I use Subversion, so that was not much of a problem. However, without a backup, these files would have been lost.
If you try out OODoc, make sure you work on a copy and use something like this
$doc->processFiles(
source => $distdir,
workdir => undef,
version => '0.1');
instead of the call to processFiles in the manpage until you know and understand what OODoc does. This will keep your source files intact, AFAIK. | [reply] [Watch: Dir/Any] [d/l] |