Serendipity Forums

Hello,

I'm currently working on the XML-RPC event plugin. One thing I noticed is that the dev docs could be improved. There are certainly more measures to improve but the top of the list would be to document data types of parameters and return values as well as the database values.

For example: https://docs.s9y.org/docs/developers/database.html describes the database fields. In serendipity_entries the column isdraft is described as

Boolean to indicate if entry is a draft

but during development I noticed it's not really boolean but a string representing a boolean value. Basically, it's (string) "true|false".

I'd like to help improve the docs but what's the proper way? Adding PHPDoc blocks everywhere? Those are missing, too, sometimes, or lack the variable names in the @param clause. The docs' website could be improved, too, by documenting the API with the docblocks. I believe, this could be at least partially automated.

Bests,
Masin

Hi! I'm sure contributions in that direction are welcome, whatever you propose would be best. Like improving function declaration comments and then automating some documentation - or just having them be better useable in IDEs for those devs that use them.

but during development I noticed it's not really boolean but a string representing a boolean value. Basically, it's (string) "true|false".

We have a converter function which converts strings like that to bools when they come from the db, https://github.com/s9y/Serendipity/blob ... c.php#L410. I'm not sure which db is causing this issue, but sqlite for example has no bool data type, and it seems like along the way this solution was used instead of converting to and from 1 and 0. Just to give a bit of context. In the PHP code itself real bools should be used.

The docs' website could be improved, too, by documenting the API with the docblocks. I believe, this could be at least partially automated.

The website is a repo: https://github.com/s9y/s9y.github.io . Changes can be pushed to there :)