On the Wiki, it is too hard to follow the path of what a function will return. For example, in TextService, there is the
FilterStringAsync function which returns a
The description for this event tells you what is returned but has no hyperlink to the actual object. (Same description for TextService used on the TextService page)
Also instead of saying it returns an
Instance it should say what the actual object it returns is, which would be
another example is PathFindingService:FindPathAsync(). There is no link to the Path instance documentation.
I’ve stated this before but I’ll mention it again just to set the record straight.
This is a limitation of Roblox’s reflection system. Roblox’s engine literally does not know what the object type is until runtime. The wiki previously worked around this by manually “augmenting” type names for every single function argument and type that needed it. The DevHub does not have this functionality, mainly because we wanted to avoid having to manually groom each member to work around these limitations. In an ideal world, the reflection system would be able to directly specify what class type each signature argument expects.
For those wondering why some properties like Constraint.Attachment0 specify their exact class name, that’s because they use a special extension of the standard property descriptor that is specifically set up to have a strong class reference, and this specific class reference can be determined when the JSON API Dump is being generated.
I would encourage you guys to push for improvements to the reflection system if you would like to see this fixed in the future. I mentioned it a few times when I was still interning at Roblox, but it seems to be a lower priority on the grand scale of things.
If that’s what is needed to get this change made then that’s what needs to be done. I don’t think moving to a new API documentation system with less information makes much sense. If Roblox wants to do this in a clean, easy-to-maintain way then they need to improve their reflection system. If Roblox doesn’t care about that then they can do it the messy way like the old wiki.
It seems silly to me that this is even an issue. Being able to look up information returned by an API call is a huge part of having documentation, and we “upgraded” and lost that ability for some API calls. In the past I’d be able to figure out pathfinding or filtering myself just by looking at the API documentation. Now i’d be unable since I can’t see what information the API calls return.
If Roblox added a “subtype” property to method info reflection data and used that here then that would be perfect.
In the specific case that @YellowoTide mentioned, this is something that can have a direct class link to the
Path class defined in the summary for the return type. Can you guys fix this @Ozzypig @polarpanda16 @cowbear16?
Thank you for bringing it to our attention! We’re taking a look into this now.
Although @Maximum_ADHD is right about the reflection system and the object types, the arguments/return types should still render links to pages when included in the summaries (which doesn’t appear to be happening right now).
If you see entries where a argument/return should have a type feel free to PM me and I’ll take a look at adding it into the summary for that object.
You’re right - moving to a new API docs system with less information definitely does not make sense. That’s why we have tools to measure how good things are*, and over time we’ve made demonstrable leaps and bounds with regards to existing documentation. It is holistically untrue to call the devhub a net downgrade in comparison to the wiki.
That said, you’re correct - this is one “con” that we also agree needs to be fixed. Clearly, the discussions have been made regarding this one feature and it’s been prioritized accordingly.
Part of what makes good documentations is the inclusion of more than just names and types; good docs also include good descriptions as well. In the meantime, we’ve made sure that many (many many many) descriptions have been updated; so in cases like these where ClassNames of Instances are missing, there’s (almost) always more information in a paragraph description. Until a complete solution is found re: the API dump, we still have the power of writing a good text description.
Also @YellowoTide regarding PathFindingService - this API is going to get some love taps in the very near future. Holding off on updating those pages until those changes are ready.
P.S. I hope everyone stops calling the new devhub “the wiki” sometime soon…since It’s not a wiki. It’s not even close to a wiki - It just fills the same need as the wiki did.
* edit: quick addendum - such tools cannot tell (without an upgraded API dump) whether the problem described in the OP is happening. So, as far as I know, we don’t have a number for how many methods this affects.