V3.16 documentation requests

Hello All,

We are improving the docs for v3.16 timeframe. How you ask? We have moved to using GitBook.io and now all English and Chinese docs will be shared under one umbrella. Part of this process is me going through documentation bugs and GitHub issues to make improvements. We are also going to be covering new topics like:

  • multi-resoultion
  • collision detection
  • integrating c++ and Objective-C
  • improved 3D examples
  • SQLite

What I would like from you us other topics that could be useful to cover and WHY? Don’t just say something like: shaders. Please be specific. Why are shaders important to you? What topics would you like to see covered? Do you already have resources and code samples we could integrate and work from?

beta docs will be built here: http://slackmoehrle.github.io/

Open the flood gates.

1 Like

Great,

Where can I find link to new cocos2dx github doc?

Regards,
Chp

I am moving around repos the next day or so and then I will post a beta build. I am tying up a few layout bugs.

1 Like

@slackmoehrle, please, when you can, explain (or put it in the doc maybe?) how to use pre-built libraries for update cocos version automatically in a created project (and how to update cocos, only writing git pull ?). I think that i’m not the only developer that has problems everytime that need update the version in an existing project. Actually, for me, is a very hard work.

Thanks

2 Likes

Good idea. I will write this.

For starters the current console development pipeline is broken because the Android SDK Tools does not support Ant from 25.3.0 (see). It is a major development pipeline for cocos2d-x but all attention is now on CocosCreator and other developers who were using or starting out to use console/ant projects are left in the dark. Only way to make it work is with the tools_r25.2.5-windows replace hack which is only mentioned in a couple of github comments -> add this to the documention until console pipleline is fixed/upgraded to clang or solved otherwise.

The Wiki has very many deprecated/useless pages… Remove them because these sorts of learning materials often instantly turn away a developer. Empty, empty. The SDK Integration main tab has only Facebook in it, this tab should be removed altogether because it implies that there is support only for Facebook. Cocos Studio, Cocos Code IDE are not developed for a long time time, why are they there as main tabs in the wiki?

There are very many nicely composed example projects with Cocos, if you were to found some ways to link/integrate these into the documentation to a certain extent that would be great. Now to be more precise, I’d define the documentation as the Programmer’s guide and the API reference (Wiki is mostly useless, if not corrupting to be honest). So most of what I mention below is for the upgrade of the API reference. Since however that has a limited format, as it has to conform to strict html boundaries as laid down by doxygen, including the example projects would be best done in the Programmer’s guide. Still, links in the API ref to the Programmer’s guide and vice versa would be very helpful. There are many mechanics in Cocos that are pretty hard to figure out how to work with because documentation(API ref) doesn’t have but the inheritence trees and member information on them. The developer is required to dive into the engine source code and analyze examples if the Programmer’s guide doesn’t talk about it.

I think the documentation for a long while has been in need of a general upgrade. There are a lot of erronous texts, gramatically. Now that I’m mentioning this, even on the main page, Programmers guide should be either Programmers’ guide, or Programmer’s guide, the latter might be better. Additionally all modules and classes that are designed for public usage should have a brief description on them, at least 2-3 meaty sentences.

All in all, most example projects should be referenced in the documentation (API ref/Programmer’s guide) in at least one place. All classes directed at public usage should have descriptions on them that mention how to use them, not just what they are (or what they seem like). And lastly, try to contain the grammatical errors. If these took place, Cocos would be a much friendlier engine to study.

2 Likes

We should probably deprecate the Wiki. I know I haven’t updated it in years. The goal was to deprecate it and move the relevant content to docs/ but this didn’t happen smoothly. There was always content that needed to be moved and deemed a lower priority.

I do agree that the api-ref often time doesn’t have a good description (probably cryptic) for each function. This could be fixed as well just by modifying the Doxygen comments as developers are in a class working with it. We always accept PR’s too.

Thank you for writing this.

Do you think integrating a number of example projects in Programmer’s guide/API ref is a good idea and doable?

I think it is a great idea. There should be more integration between what you read in the docs and what the API is used for. We have talked about this a lot in the past. I think we just need to act upon it and see what happens.

The new docs are in an alpha: http://slackmoehrle.github.io

Looks very neat! Different segments of the doc’s are more interconnected as well in this way.

I was thinking of adding an API Ref tab alongside the c++ and Javascript code tabs. But, that could be a very long piece of text and you probably don’t need to see the whole API-Ref all at once. Perhaps I can just show the most important functions.

Or, I had also thought, where ever you see Sprite, for example, could be a link to the API-Ref, but then that would navigate you from the page unless we open it in a new tab/window.

I want the docs about distance field shader be covered. I have this problem now Font: Distance Field Label Shader
The problem with font down scaling.

I would like to see the definitions of game engine terms. You can look at Unity docs for example - you don’t need to look to anywhere else to understand every things in it. Unity docs is really nice, we can learn from it.

1 Like

Ok good idea. I can do this.

What about my shader question?

I don’t know the answer to your question off hand.

Add info about what fonts are available on which platforms.

Link is not working… Page not found…

Yup I will put a new build out there in a few hours.