Question on object property formats

[pfwd]

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.

[pjedrzejewski]

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

[umpirsky]

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.

[pjedrzejewski]

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.

[umpirsky]

@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. :)

[pfwd]

👍 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

• The script will need access to Sylius
• Make sure we only get the relevant properties/classes
• Dynamically formatting the tables might be tricky

2. Integrate this into the sphinx build process

• Might require a separate build script to generate the property files before running the build

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)