So, first of all thank you a lot @stevebaer also from my side!
Regarding the docs: I definitely don’t want to lecture any of you guys so please don’t get this the wrong way. Sometimes it helps to employ strict rules when there is a lack regarding docstrings - in my opinion filling out docstrings should not be a “yeah yeah later” thing - just make it mandatory for merging into master branch or something like that. In my personal experience documentation that is not there from the get go will never ever be there because one will simply not do it at a later time.
PS: I’ll mention my OCD again and make the following suggestion: Why not make a documentation submission feature and involve your community (people like me who are actually having fun making things tidy)? Just trying to be constructive
Do the language specific syntax tabs even make sense? It seems like they can make things worse as people are searching for a python tab. I’ve been redesigning the API documentation site and chose not to even have the what I consider confusing C#/VB tabs for syntax and always just default to C# syntax.
Note, this is just a prototype site that I use and is not the official API documentation.
Here’s the current page for that function to compare
You could be right there. I would argue that language specific syntax tabs might confuse. For new people it is difficult to understand in which language you can work and in which you can’t. When I started it took me a lot of time to understand that basically everything in RC is available across all three languages.
I think what might be needed is some marker (box or similar) to show that this is the actual syntax of the api and not just some headline.
I really like that you kept the Example tabs for all three different languages, like here. Although there should be a better way for navigating out of the example view again.
But of course you said it’s only a prototype. I just wanted to give some feedback, thank you for your efforts!
It’s tough to enforce comments for all new commits. I’ve seen systems like this and they tend toward people making absolutely useless comments just because they have to. For example, writing a summary of “a constructor” for a constructor of a class. These comments can clutter sites and just add words for no benefit.
I do like the idea of allowing the community to improve the docs. We have enough pieces open source that this would be possible. We could add a link on each page for the prototype site to source that could be edited for documentation.
I’m not referring to samples. For those I agree that language specific versions are necessary. I’m referring to the syntax tabs mentioned above. These are for the signature of a method
Yes, of course you’re absolutely right there! Did not think of that and had to laugh at myself because I came accross many APIs where this is true
I would really really love this. There are a ton of examples also on this forum that could be transitioned to the docs site etc. I feel that Rhino/Grasshopper/RhinoCommon actually has lots and lots of resources and examples but they tend to be really scattered around different sites/forums/etc. If this could somehow be bundled it would surely ease entry for new people.
Anyhow, one last question since this is all going super ot here and has nothing to do with SQLite anymore: @stevebaer could you split this topic into a new discussion about the documentation/user contribution idea or something?
