search

silverstripe / api.silverstripe.org

API documentation for the Silverstripe Framework
BSD 3-Clause "New" or "Revised" License
3 stars 14 forks source link

Invalid docblock syntax breaking Datetime.Format API docs #101

Closed Sil3ntStorm closed 11 months ago

Sil3ntStorm commented 5 years ago

Affected Version

SS 4.3

Description

DateTime.Format in a template used to work fine, now gives broken results like 16/33/2018 The date is correctly stored in the database and is correctly retrieved if dumped in PHP before used in template.

Steps to Reproduce

Give the template a datetime from the database and call Format on it in the template code.

The documentation on api.silverstripe.org gives nothing but the format string as an explanation for the format parameter (in fact not even that, it's just described as that in a side sentence for the function itself). Obviously proper format strings that are well known and which people are used to don't work. One has to Google for the issue (after figuring out the display is what's broken), then find a Stackoverflow Question that then links some ominous changelog which contains some remote mention of it in one of its thousands of lines... Then you have to Google the format to actually find any helpful information. That's like 10 steps, where one should suffice. Took me like an hour to find the necessary information to change a few characters in the template...

This is ridiculous BS, really pissed off....

ScopeyNZ commented 5 years ago

Hey @Sil3ntStorm . Do you mind linking to the specific parts of the documentation?

All our our developer docs are open source - and in this repo:

https://github.com/silverstripe/silverstripe-framework/tree/4/docs/en

The folder structure follows the navigation on the website. We'd be happy to receive and review any pull requests updating this documentation. If you're not sure about the contribution process I'll be happy to raise a PR on your behalf if you have some specific suggestions.

Sil3ntStorm commented 5 years ago

This is about the API documentation for the function The documentation you linked is more bare bone basic stuff with long winded texts.

tractorcow commented 5 years ago

The problem is the docs generator. Compare the actual docs in code for that parameter:

* @param string $format Format code string. See http://userguide.icu-project.org/formatparse/datetime

Vs the docs the generator has created.

$format

If you had checked the code itself you could have saved yourself an hour of frustration. Typically SilverStripe code aims to be self-documenting.

tractorcow commented 5 years ago

@ScopeyNZ can you please re-run the docs generation and check if it resolves the issue there?

Sil3ntStorm commented 5 years ago

@tractorcow I don't necessarily have the entire base code lying around locally tbh, but I guess from now on I might actually do that, though it really shouldn't be necessary to dig through tons of code for that.

Looking at it though, could it possibly be that the generator tripped over the fact that the comment parameter specification doesn't match the actual function signature? Seeing you've got comments for two parameters when the function only takes one.

robbieaverill commented 5 years ago

@Sil3ntStorm you're probably right. If the phpdoc is invalid then it won't end up on the API documentation. We'd welcome a pull request to fix it!

GuySartorelli commented 11 months ago

Looks fine now - I'm not sure what the original problem was, but the "Format code string. See https://unicode-org.github.io/icu/userguide/format_parse/datetime" message is displaying in http://api.silverstripe.com/4/SilverStripe/ORM/FieldType/DBDatetime.html#method_Format, which I think is what this issue is about.