| Re: Major trouble with PhpDocumentor [message #182325 is a reply to message #182316] |
Sun, 28 July 2013 14:36   |
Scott Johnson
Messages: 196
Registered: January 2012
Karma:
|
Senior Member |
|
|
On 7/27/2013 9:04 PM, Fiver wrote:
> 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
>
Wow fiver.
Jerry simply gave you a reference of where you 'might' find better
advice and you fight him at every turn to the point of being sarcastic.
He never said you where stupid or would not find help here, just gave
you a suggestion.
Makes me think now if anyone had advice on how to fix your issue you
might fight them as well.
Good luck.
Scotty
|
|
|
|
Calendar
Search
Help
Members
Register
Login
Home
]