| Re: Major trouble with PhpDocumentor [message #182316 is a reply to message #182315] |
Sun, 28 July 2013 04:04   |
Fiver
Messages: 35
Registered: July 2013
Karma:
|
Member |
|
|
On 2013-07-28 04:59, Jerry Stuckle wrote:
> On 7/27/2013 10:45 PM, Fiver wrote:
>> On 2013-07-28 04:22, Jerry Stuckle wrote:
>>> Personally, much of my code is documented before any code is written
>>> (it's called a "design"). It may or may not be a complete design,
>>> depending on the complexity of the project. But the rough outlines are
>>> there. Then I add any additional details as I go along.
>>
>> Okay, but what do you use to process your inline documentation?
>> Design, documentation and tests first is a nice principle, but I've
>> never seen a (non-trivial) project go from design to production without
>> significant changes. Having to maintain separate documentation files in
>> parallel to the source is asking for trouble, IMHO. But to each their own.
> None of my projects require *significant* changes, unless it is due to
> changes from the client. But then I started a long time ago (when
> flowcharts were popular) and have quite a few projects under my belt.
> And I do *complete* designs - not just some minimal scratches on a
> notepad. It saves me a lot of time because I write code once and am
> done. I don't need to keep going back to change things because of
> something I didn't consider previously.
>
> And no, maintaining separate documentation files is *critical* to a good
> project. These are the documents the test group use to ensure the code
> is written according to the documentation. It is also the first place
> changes due to client requests or design deficiencies are applied. The
> code is written to support the design.
>
> The test group doesn't even look at the code. It looks at the
> documentation to ensure the code runs according to the spec. It's
> harder to separate coding from testing when you do both jobs, but it can
> be done (and becomes easier with practice).
You're clearly talking about an entirely different type of documentation
here. This sound more like a specification than what I had in mind: an
API reference. The documents you're describing answer the question "What
should this part do?", whereas what I'm talking about answers questions
like "What type of parameters does this method accept?" and "What's the
name of the method that returns a list of Foo objects?". A developer
reference. The typical case for inline documentation.
I have to admit that I'm tremendously impressed by the way your projects
work out. No significant changes; projects don't evolve over the years;
everything turning out as planned from the start - it sounds fantastic.
Practically unique in the world of large-scale software development. Kudos.
> And no, I doubt very much anyone here uses PHP Documentor. And if it
> ever was the "number one documentation generator for php", it still
> wasn't very popular. You're one of the few people I've ever heard of who
> uses it.
>
> You can hang around all you want - no one's going to stop you. But
> you're going to get better help through their support structure.
I'm beginning to suspect that you're right about that, judging from the
feedback I got so far. Nevertheless, I'll wait and see if I can get a
reply from someone who has actually used a tool to generate
documentation before. It's not that much of an outlandish idea.
If you're unsure of what I mean, here are some examples (using
PhpDocumentor/DocBlox):
http://framework.zend.com/apidoc/1.11/
http://apidocs.sugarcrm.com/api/6.7.1/pro/
http://pear.php.net/package/Mail/docs/latest/
http://roundcube.net/doc/phpdoc/
http://www.agavi.org/apidocs/index.html
You've probably heard of these projects before. You can find more
examples by searching the web for "This documentation was generated by
PhpDocumentor" or "This documentation was generated by DocBlox". If
you're entirely new to the concept, look up JavaDoc.
regards,
5er
|
|
|
|
Calendar
Search
Help
Members
Register
Login
Home
]