I think the codebase could benefit (at least be more accessible to developers new to it) if there were more comments describing the various elements. Java famously has Javadoc which generates nicely formatted HTML documentation from comments written in the code. I've used Natural Docs (another Sourceforge project) to achieve similar results with both PLSQL and VBA projects and can recommend it. Things I like about it is that it's free (it doesn't rely on having an expensive tool like Toad), configurable, generates nice HTML output and the comments in the code are very readable on their own.
Any thoughts?
Has anyone else used anything for generating this kind of documentation for PLSQL?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Initial indications from the "plsqldoc" project Bill mentioned aren't promising. I can find just about nothing in the way of documentation for how to use it and so far I've only got errors when I try running it! I've logged a support ticket, so we'll see what happens...
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I haven't had any great success with any of the other tools mentioned. They either don't produce the kind of documentation I'm looking for, don't have sufficient instructions for to work out how to use them, etc, etc. I've tried requesting support form one or two but had no response.
Unless I find anything better in the meantime, I think I'll probably go with Natural Docs. I know from experience that it works and the developer is very helpful in responding to queries!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
The documentation of code isn't a bad idea.
I'd rather see documentation in a form of specification by example - that is:
Each functionality should have sample code with a real life use-case.
It seems to be most trendy nowadays as most people learn things fast by seeing examples of use cases.
Those examples could also show some good patterns and prevent people from using anti-patterns when writing their tests.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I suppose there's two levels of documentation - guides for people using utPLSQL and API information for people working on the actual utPLSQL code itself. I think you're right about documenting with examples to help users. What I was thinking of here was more the second type, to help anyone looking at how utPLSQL itself works.
I assume you've seen the current documentation - is this along the lines of what you're describing?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Hi Paul,
Yes I've seen the current documentation. It shows some basic exaples, but they are often incomplete and are missing the user guide quality, that is they do not provide a guide to learn step by step how to use entire power of the utility.
I was thinking about RSpec doc as an example of how the specification by example can be used do describe functionality. http://rspec.info/documentation/3.3/rspec-core/ http://www.relishapp.com/rspec/rspec-expectations/docs
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Now that i think about it...
We could join the effort of testing utPLSQL with documenting it.
We could have example use cases (as simpe as possible).
Those examples should be part of testing siute for utPLSQL.
Executing those examples should be proving that particular pieces of utPLSQL are working.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I think the codebase could benefit (at least be more accessible to developers new to it) if there were more comments describing the various elements. Java famously has Javadoc which generates nicely formatted HTML documentation from comments written in the code. I've used Natural Docs (another Sourceforge project) to achieve similar results with both PLSQL and VBA projects and can recommend it. Things I like about it is that it's free (it doesn't rely on having an expensive tool like Toad), configurable, generates nice HTML output and the comments in the code are very readable on their own.
Any thoughts?
Has anyone else used anything for generating this kind of documentation for PLSQL?
Did you look at "plsqldoc" project? I haven't used it myself.
https://sourceforge.net/projects/plsqlutils/
No, I hadn't seen that. I'll take a look. Thanks Bill
Initial indications from the "plsqldoc" project Bill mentioned aren't promising. I can find just about nothing in the way of documentation for how to use it and so far I've only got errors when I try running it! I've logged a support ticket, so we'll see what happens...
I've been Googling and have found these tools that also sound like they might do the job:
I'll have a look at them in due course and report my findings...
Just a quick update...
I haven't had any great success with any of the other tools mentioned. They either don't produce the kind of documentation I'm looking for, don't have sufficient instructions for to work out how to use them, etc, etc. I've tried requesting support form one or two but had no response.
Unless I find anything better in the meantime, I think I'll probably go with Natural Docs. I know from experience that it works and the developer is very helpful in responding to queries!
+1 for Natural Docs, the syntax is very clean and "natural" for read.
The documentation of code isn't a bad idea.
I'd rather see documentation in a form of specification by example - that is:
Each functionality should have sample code with a real life use-case.
It seems to be most trendy nowadays as most people learn things fast by seeing examples of use cases.
Those examples could also show some good patterns and prevent people from using anti-patterns when writing their tests.
I suppose there's two levels of documentation - guides for people using utPLSQL and API information for people working on the actual utPLSQL code itself. I think you're right about documenting with examples to help users. What I was thinking of here was more the second type, to help anyone looking at how utPLSQL itself works.
I assume you've seen the current documentation - is this along the lines of what you're describing?
Hi Paul,
Yes I've seen the current documentation. It shows some basic exaples, but they are often incomplete and are missing the user guide quality, that is they do not provide a guide to learn step by step how to use entire power of the utility.
I was thinking about RSpec doc as an example of how the specification by example can be used do describe functionality.
http://rspec.info/documentation/3.3/rspec-core/
http://www.relishapp.com/rspec/rspec-expectations/docs
Now that i think about it...
We could join the effort of testing utPLSQL with documenting it.
We could have example use cases (as simpe as possible).
Those examples should be part of testing siute for utPLSQL.
Executing those examples should be proving that particular pieces of utPLSQL are working.