Graphite
Graphite copied to clipboard
cgutteridge
Merge external docs with api docs where appropriate
At the moment there's graphite-docs.html but not too much in the way of API docs.
At some point or another, we should merge the two and rely on tools like doxygen or phpdocumentor/docblox to generate it for us. This would be a good move because the documentation can appear inline in a lot of common IDEs; and we can automate generation of docs from source.
Example slick docs by phpdocumentor: http://demo.phpdoc.org/
I don't rate those 'slick' docs... they are fancy and all but I don't see them as more useful than something more straight forward. So long as I can generate something VERY similar to graphite-docs.html I'm happy. It's important to document that most graphite functions can take a variety of inputs (string, resource, resource list, array of strings, array of resources). It makes it really easy to code, but your
I really hate mechanically produced docs which have not had some care and attention paid to the final result, although the inline-documentation is a neat feature, but I've never needed it, and never been asked for it so it's a bit of a read herring if it makes it harder to maintain the library. It's not primarily aimed at high end enterprise people but was aimed to make it easier and more fun to hack code. Lose that and I'll be sad!
Actually... I'm inclined when the next version goes out to write a packager which just bundles together all of the php files into one package for people who still want the quick and dirty solution... but keep them separate in the codebase. Best of both worlds!
On 19/03/2012 13:08, Daniel O'Connor wrote:
At the moment there's graphite-docs.html but not too much in the way of API docs.
At some point or another, we should merge the two and rely on tools like doxygen or phpdocumentor/docblox to generate it for us. This would be a good move because the documentation can appear inline in a lot of common IDEs; and we can automate generation of docs from source.
Example slick docs by phpdocumentor: http://demo.phpdoc.org/
Reply to this email directly or view it on GitHub: https://github.com/cgutteridge/Graphite/issues/5
Christopher Gutteridge -- http://id.ecs.soton.ac.uk/person/1248
Graphite PHP RDF Library v1.5 released! http://graphite.ecs.soton.ac.uk/ University of Southampton Open Data Service: http://data.southampton.ac.uk/ You should read the ECS Web Team blog: http://blogs.ecs.soton.ac.uk/webteam/
On Tue, Mar 20, 2012 at 8:27 PM, Christopher Gutteridge < [email protected]
wrote:
I don't rate those 'slick' docs... they are fancy and all but I don't see them as more useful than something more straight forward. So long as I can generate something VERY similar to graphite-docs.html I'm happy. It's important to document that most graphite functions can take a variety of inputs (string, resource, resource list, array of strings, array of resources). It makes it really easy to code, but your
I really hate mechanically produced docs which have not had some care and attention paid to the final result, although the inline-documentation is a neat feature, but I've never needed it, and never been asked for it so it's a bit of a read herring if it makes it harder to maintain the library. It's not primarily aimed at high end enterprise people but was aimed to make it easier and more fun to hack code. Lose that and I'll be sad!
Actually... I'm inclined when the next version goes out to write a packager which just bundles together all of the php files into one package for people who still want the quick and dirty solution... but keep them separate in the codebase. Best of both worlds!
I reckon you can get a nice mix of both style of docs - API docs ripped out of the methods and end user manuals.
An example, what we do in PEAR Manual: http://pear.php.net/manual/en/package.validate.validate.intro.php API docs: http://pear.php.net/package/Validate/docs/latest/Validate/Validate.html
Where graphite-docs.html is doing API documentation like things; I think we should stick those into the code. Where it's usage manual, I think that's where the focus should be.
Let me pull together a few examples over the coming days :)
I am really not sold. Don't touch the HTML docs yet. I'm going to try to walk a line between not discouraging you, but not being pushed so far out of my comfort zone I'll stop enjoying giving up my Sundays to work on the codebase.
On 20/03/2012 23:06, Daniel O'Connor wrote:
On Tue, Mar 20, 2012 at 8:27 PM, Christopher Gutteridge< [email protected]
wrote: I don't rate those 'slick' docs... they are fancy and all but I don't see them as more useful than something more straight forward. So long as I can generate something VERY similar to graphite-docs.html I'm happy. It's important to document that most graphite functions can take a variety of inputs (string, resource, resource list, array of strings, array of resources). It makes it really easy to code, but your
I really hate mechanically produced docs which have not had some care and attention paid to the final result, although the inline-documentation is a neat feature, but I've never needed it, and never been asked for it so it's a bit of a read herring if it makes it harder to maintain the library. It's not primarily aimed at high end enterprise people but was aimed to make it easier and more fun to hack code. Lose that and I'll be sad!
Actually... I'm inclined when the next version goes out to write a packager which just bundles together all of the php files into one package for people who still want the quick and dirty solution... but keep them separate in the codebase. Best of both worlds!
I reckon you can get a nice mix of both style of docs - API docs ripped out of the methods and end user manuals.
An example, what we do in PEAR Manual: http://pear.php.net/manual/en/package.validate.validate.intro.php API docs: http://pear.php.net/package/Validate/docs/latest/Validate/Validate.html
Where graphite-docs.html is doing API documentation like things; I think we should stick those into the code. Where it's usage manual, I think that's where the focus should be.
Let me pull together a few examples over the coming days :)
Reply to this email directly or view it on GitHub: https://github.com/cgutteridge/Graphite/issues/5#issuecomment-4607520
Christopher Gutteridge -- http://id.ecs.soton.ac.uk/person/1248
Graphite PHP RDF Library v1.5 released! http://graphite.ecs.soton.ac.uk/ University of Southampton Open Data Service: http://data.southampton.ac.uk/ You should read the ECS Web Team blog: http://blogs.ecs.soton.ac.uk/webteam/