Tobias Schlitt wrote:
> During development of the Webdav component Kore and me agreed to add an
> extra new-line to the doc-blocks we created, directly after the short
> description. Instead of
>
> /**
> * This is the short description.
> * This is the long description which is very very long and even longer
> * and much longer as the short one and can possibly contain even more
> * and more text as you can see here...
> */
>
> our doc-blocks in Webdav look like
>
> /**
> * This is the short description.
> *
> * This is the long description which is very very long and even longer
> * and much longer as the short one and can possibly contain even more
> * and more text as you can see here...
> */
>
> While I was first not much for this idea, I like it much better now and
> find it much more readable, when reading through the code. In addition,
> it avoids the mixup of short and long description to some degree (no
> short description, but the long desc starting on the first line of the
> doc-block). The latter issue can lead to very ugly online docs, where
> half sentences occur as short description.
>
> I would suggest that we make this our standard for doc-blocks and
> successively (or by script) update the docs.
>
> What do you think?
+1
--
Components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/components
