0 Members and 2 Guests are viewing this topic.
Example:Code: [Select]Before: EXP▶Hex Converts the number to hexadecimal and returns the pointer to that string. Code: [Select]After: EXP▶[HEX] -> PTR Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.
Before: EXP▶Hex Converts the number to hexadecimal and returns the pointer to that string.
After: EXP▶[HEX] -> PTR Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.
On the topic of Axe documentation...We used to have an Axe wiki, where this kind of stuff (tutorials and “better” documentation) can be found. Mediawiki needed to be updated 24/7 though, and things got messy so fast (spambot fiesta!) that it was eventually shut down.(See: http://www.omnimaga.org/news/axe-parser-wiki-opens-its-doors/msg220368/#msg220368)I don’t think we’ll ever put up another wiki again (unless it’s some other wiki software, NOT Mediawiki). But if you’re really interested in improving documentation, you can either modify the current one (that one HTML file), or get your hands messy by creating another one!Sphinx (http://sphinx-doc.org/) is a documentation format that creates pretty documentation from simple markup. LOTS of projects use it, and although it is a little overkill for a project like Axe, you can certainly use it to provide meatier details about Axe, including tutorials and the likes. I’d love to see a https://axe.readthedocs.org/ one day!EDIT: Looks like thep ninja'd me!
Instead of fighting about this, can we just agree that although the current documentation is complete, more could be desired?For instance, if we compare the axe commands to the android documentation we can see that the android documentation is very thorough to the point that after reading it, you really shouldn't have any questions. (this is the documentation for Camera.open()). But, if you look at the android documentation, you'll see that it takes more than half of your screen for one command. The purpose of commands.html is to put everything in front of you in a concise way so sometimes the 100% complete explanation isn't given. Whatever happened to that axe wiki? I feel like that's probably the best place for the kind of information you want. A wiki can be as verbose as you like and can provide the actual 100% explanation.
Nothing wrong with mediawiki, you just have to secure it properly. It's what the largest wiki in the world uses after all (Wikipedia).
Example:Code: [Select]Before: EXP▶Hex Converts the number to hexadecimal and returns the pointer to that string. Code: [Select]After: EXP▶[HEX] -> PTR Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.The red is not needed, but if you want the pointer to go somewhere you should provide this information.
Quote from: josh landers on March 20, 2014, 01:16:06 pmExample:Code: [Select]Before: EXP▶Hex Converts the number to hexadecimal and returns the pointer to that string. Code: [Select]After: EXP▶[HEX] -> PTR Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.The red is not needed, but if you want the pointer to go somewhere you should provide this information. You know you start modifying the documentation with stuff like that and then submit it to Runer112 to include in the official releases.
Quote from: alberthrocks on March 20, 2014, 01:50:28 pmOn the topic of Axe documentation...We used to have an Axe wiki, where this kind of stuff (tutorials and “better” documentation) can be found. Mediawiki needed to be updated 24/7 though, and things got messy so fast (spambot fiesta!) that it was eventually shut down.(See: http://www.omnimaga.org/news/axe-parser-wiki-opens-its-doors/msg220368/#msg220368)I don’t think we’ll ever put up another wiki again (unless it’s some other wiki software, NOT Mediawiki). But if you’re really interested in improving documentation, you can either modify the current one (that one HTML file), or get your hands messy by creating another one!Sphinx (http://sphinx-doc.org/) is a documentation format that creates pretty documentation from simple markup. LOTS of projects use it, and although it is a little overkill for a project like Axe, you can certainly use it to provide meatier details about Axe, including tutorials and the likes. I’d love to see a https://axe.readthedocs.org/ one day!EDIT: Looks like thep ninja'd me!Nothing wrong with mediawiki, you just have to secure it properly. It's what the largest wiki in the world uses after all (Wikipedia).
Quote from: josh landers on March 20, 2014, 01:16:06 pmExample:Code: [Select]Before: EXP▶Hex Converts the number to hexadecimal and returns the pointer to that string. Code: [Select]After: EXP▶[HEX] -> PTR Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.The red is not needed, but if you want the pointer to go somewhere you should provide this information. I don't agree that this should be written, or at least not by default, because maybe you don't want to store that pointer, maybe you just want to use it once and you'll just write for example Text(0,,18▶Hex), so your "→Ptr" appears nowhere.However, something that could be done (but probably annoying to do) is a button next to each command that expands a box showing examples about how to use that command or more information or whatever. But I still think that the current presentation is fine, with only one concise line about what it takes and what it returns showed by default, hence why I'd say there should be that button (a bit like with spoilers on forums in fact).
Author
Topic: [Controversial] Better Axe Documentation Could Be Needed (Read 17922 times)
