Mismatched Documentation

Haxe
#1

Hi all,

I’ve been working on learning Haxe and OpenFL for personal/hobby games, and I’ve had trouble browsing the documentation as a usage guide. Several function and field descriptions seem mismatched on the API website. Perhaps this mismatch is due to commented-out code in the source?

For example, in openfl.text.TextField, the variable antiAliasType has the description:

When set to true and the text field is not in focus, Flash Player highlights the selection in the text field in gray. When set to false and the text field is not in focus, Flash Player does not highlight the selection in the text field.

The link to that page is here.

In the source code on my machine (which haxelib reports to be OpenFL 9.0.2), the following snippet can be found:

	/**
		When set to `true` and the text field is not in focus, Flash Player
		highlights the selection in the text field in gray. When set to
		`false` and the text field is not in focus, Flash Player does not
		highlight the selection in the text field.

		@default false
	**/
	// var alwaysShowSelection : Bool;

	/**
		The type of anti-aliasing used for this text field. Use
		`openfl.text.AntiAliasType` constants for this property. You can
		control this setting only if the font is embedded(with the
		`embedFonts` property set to `true`). The default
		setting is `openfl.text.AntiAliasType.NORMAL`.

		To set values for this property, use the following string values:
	**/
	public var antiAliasType(get, set):AntiAliasType;

From this point of view, the alwaysShowSelection variable seems to be the culprit of the mismatch. However, I’m also concerned by the fact that I can’t seem to find this same snippet of code on GitHub, even when browsing under the 9.0.2 tag. On Github, the alwaysShowSelection variable seems to have been removed entirely.

So my primary two questions are:

  1. How can I get the documentation in my local code editor to reflect the proper description? (I use Visual Studio Code, though I think my question applies to all local editors.)
  2. When will the published online documentation be updated to reflect these changes?

Tangentially, I am also curious:

  1. Why is the source code on my machine different than what is tagged on GitHub? The file path to TextField.hx is: C:\HaxeToolkit\haxe\lib\openfl\9,0,2\packages\textfield\src\openfl\text\TextField.hx.

Thank you for your help.

#2

Hi @RNanoware,
I don’t know the process for publishing the API docs, but I do know that the local code editor will always show the documentation shown in the currently active library you have locally. So in your case, it is getting it from the files at C:\HaxeToolkit\haxe\lib\openfl\9,0,2\
If you want to ensure your local version matches what is the most recent version online you might want to try setting up haxelib to use the git repo.
I hope that helps a bit!

#3

Here’s the instructions for that. https://lib.haxe.org/documentation/using-haxelib/#git

#4

Thanks for the info! I had forgotten that Haxelib allows for pulling directly from Git—I’ll have to try that out.

It still strikes me as curious why the version of the code pulled from the Haxelib server itself would have differences compared with the Git repo tagged with the same version, but of course there are many variables (build/deployment steps, etc) that I’m probably unaware of.

#5

We were going to try and have the documentation hosted in a different location from the implementation to reduce the size of the files and to help make it cleaner for internal development. I think this will be reversed in the next release so that each file under “src” will have the same documentation seen in the API documentation

#6

Ah, that makes sense! Thank you for the clarification. Does the current setup mean that there is another dedicated OpenFL documentation repository somewhere?

#7

Honestly, I would be open to feedback whether a separate repository dedicated only to documentation would be better. I had not thought about this before.

Benefits:

1.) Documentation only. Want to improve docs? One clear place to do it
2.) The source code could be free of documentation, making it easier to find/replace and jam around

Downside:

1.) No inline code documentation while writing within an IDE

I’m guessing the downside is a big one, and makes it worth keeping the code and docs all together?

#8

Although I agree that the disadvantage of no (easily accessible) inline IDE documentation is formidable, I personally would be glad to put in the extra effort of synchronizing the code and docs in my own development environment if the process itself is well documented. Shoot, I would even be okay if the syncing process was impossible, and the code/docs were entirely separated, so long as the standard is communicated clearly for developers who are either using or contributing to the library.

At the end of the day, simply the existence of high-quality documentation is what I most love to see in any project, and I am happy to support whatever workflow is necessary to make that vision a reality for OpenFL. What worries me is, as you alluded to, a fragmented documentation across multiple repositories that leads to other developers asking questions about common obstacles (and unable to share their discoveries via doc contributions).

#9

Sorry for the late update

We chose to simplify and merge it all together. It should all be present now in the https://github.com/openfl/openfl repository on the develop branch

1 Like
#10

For the less sophisticated among us who don’t know how to contribute code, and wouldn’t dare try it if we did, is there a process or place for suggesting documentation changes?