Open pfwd opened 8 years ago
OK, so this is really messy. :/ I am on the edge to be honest, visually tables are best IMHO, but on the other hand they are very annoying to add/change. List are simplest I think. We should decide right now, cause we have plenty of new documentation incoming. :) Please share your thoughts everyone.
/cc @Sylius/core-team
Tables are perfect, I don't think they are pain to maintain.
Would be uber cool to automate this somehow, to be generated form apidoc or link pages which contain this data to make maintenance easier.
The thing is that these docs should describe it more from the domain point of view, we have code docs in phpdoc blocks and api.sylius.org. :) But I think I'd vote +1 for the tables too.
@pjedrzejewski I don't see the reason to have domain point of view descriptions in code docs too.
Stupid random example, we have in Product.php
now:
/**
* @var \DateTime
*/
protected $createdAt;
And in docs: createdAt - Date of creation
We can instead have:
/**
* Date of creation.
*
* @var \DateTime
*/
protected $createdAt;
or maybe better example:
/**
* Simple description of the product for lists and banners.
*
* @var string
*/
protected $shortDescription;
And in general we need better more verbose descriptive docblocks instead copy pasted property names as we have on many places. Some of them written by me. :)
:+1: To using tables
A thought about automating the process. (If we went down that road of course) We could write a php script that uses reflection to pull out class properties and their doc comments. These could be written to a file per class and stored in the Sylius-Doc repo under /_automation/properties/ The script could write these as rst files in a table format. We could then include the file in the Sphinx doc page like so:
Product Attributes .. include:: /_automation/product.rst
Of course this is easier said than done.
1) Write the script
2) Integrate this into the sphinx build process
3) Update the pages in the doc to include the relevant property file
At the very least I think we should have a link to the corresponding api doc that @pjedrzejewski mentioned above. http://www.api.sylius.org (I didn't even know that existed and I can't see it in the docs)
What's the preferred way to document object properties?
I see lots of different examples: http://docs.sylius.org/en/latest/book/channels.html Does it by a list. Name of property is in bold followed by an indented description.
http://docs.sylius.org/en/latest/book/products.html does it by a list but with property names in italics and their descriptions on the same line
http://docs.sylius.org/en/latest/book/addresses.html Does it by a bulleted list with no description
http://docs.sylius.org/en/latest/book/orders.html Does it by a table with Attribute and Description columns.
Or is there another way that it could be done. Perhaps automatically by a third party application.