Skip to main content
Software Engineering

Return to Question

replaced http://stackoverflow.com/ with https://stackoverflow.com/
Source Link
Community Bot
Community Bot
  • 1

I have an large php project. I used to document it with NaturalDocs, but I didn't include the documentation generation in the build process for a long time ( years ).

I recently started using composer and looked into PSR. The only standard way to document my code seems to be docblocks for phpdocumentor.

Since my code is only in part object oriented and contains much procedural files, I cannot only rely on documenting classes and functions, but I have alot of file level documentation.

It turns out that page level docblocks are not well supported in phpdocumentor ( see http://stackoverflow.com/questions/26925742/page-level-docblocks-and-phpdocumentor-templateshttps://stackoverflow.com/questions/26925742/page-level-docblocks-and-phpdocumentor-templates ). Therefore I'm really stuck now.

To conclude my questions :

Does it make sense to document non object oriented code with docblocks and phpdocumentor ? Is phpdocs a good choice here ? Is my approach to professionnalize the documentation of our project viable or is it somehow flawed ?

I have an large php project. I used to document it with NaturalDocs, but I didn't include the documentation generation in the build process for a long time ( years ).

I recently started using composer and looked into PSR. The only standard way to document my code seems to be docblocks for phpdocumentor.

Since my code is only in part object oriented and contains much procedural files, I cannot only rely on documenting classes and functions, but I have alot of file level documentation.

It turns out that page level docblocks are not well supported in phpdocumentor ( see http://stackoverflow.com/questions/26925742/page-level-docblocks-and-phpdocumentor-templates ). Therefore I'm really stuck now.

To conclude my questions :

Does it make sense to document non object oriented code with docblocks and phpdocumentor ? Is phpdocs a good choice here ? Is my approach to professionnalize the documentation of our project viable or is it somehow flawed ?

I have an large php project. I used to document it with NaturalDocs, but I didn't include the documentation generation in the build process for a long time ( years ).

I recently started using composer and looked into PSR. The only standard way to document my code seems to be docblocks for phpdocumentor.

Since my code is only in part object oriented and contains much procedural files, I cannot only rely on documenting classes and functions, but I have alot of file level documentation.

It turns out that page level docblocks are not well supported in phpdocumentor ( see https://stackoverflow.com/questions/26925742/page-level-docblocks-and-phpdocumentor-templates ). Therefore I'm really stuck now.

To conclude my questions :

Does it make sense to document non object oriented code with docblocks and phpdocumentor ? Is phpdocs a good choice here ? Is my approach to professionnalize the documentation of our project viable or is it somehow flawed ?

Notice removed Draw attention by Arseni Mourzenko
Bounty Ended with Lorenz Meyer's answer chosen by Arseni Mourzenko
Notice added Draw attention by Arseni Mourzenko
Bounty Started worth 50 reputation by Arseni Mourzenko
Tweeted twitter.com/#!/StackProgrammer/status/534359365394776065
Source Link
Lorenz Meyer
Lorenz Meyer
  • 383
  • 2
  • 11

How to move php documentation closer to standards?

I have an large php project. I used to document it with NaturalDocs, but I didn't include the documentation generation in the build process for a long time ( years ).

I recently started using composer and looked into PSR. The only standard way to document my code seems to be docblocks for phpdocumentor.

Since my code is only in part object oriented and contains much procedural files, I cannot only rely on documenting classes and functions, but I have alot of file level documentation.

It turns out that page level docblocks are not well supported in phpdocumentor ( see http://stackoverflow.com/questions/26925742/page-level-docblocks-and-phpdocumentor-templates ). Therefore I'm really stuck now.

To conclude my questions :

Does it make sense to document non object oriented code with docblocks and phpdocumentor ? Is phpdocs a good choice here ? Is my approach to professionnalize the documentation of our project viable or is it somehow flawed ?