Improving documentation

Discussion corner for Developers of Serendipity.
Post Reply
MasinAD
Posts: 1
Joined: Sat Jan 11, 2020 11:35 am

Improving documentation

Post by MasinAD » Sat Jan 18, 2020 12:07 pm

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

User avatar
onli
Regular
Posts: 2371
Joined: Tue Sep 09, 2008 10:04 pm
Contact:

Re: Improving documentation

Post by onli » Sat Jan 18, 2020 12:25 pm

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

Post Reply