Jump to content
  • Advertisement
Sign in to follow this  
deftware

Painless Documentation of a Custom Scripting Language

This topic is 856 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

 I'm trying to find a decent solution that would allow me to document my game's scripting language. The language itself is command-based and thusly comprises various sets of commands that deal with different aspects of the game engine and game logic.

 

 My initial plan was to just write a big long text file called "scripting.txt" and include it with my game, but that didn't seem very inviting or intuitive for users who want to figure out how to make stuff.

 

 I'm trying to find something that will let me easily document my command-based scripting language for my game, and present it to people in a concise fashion. I'd like to be able to list the command groups, and then the individual commands within those groups, where each command is a link to a detailed description of the command and usage examples.

 

 The closest thing I can think of to what I am looking to create is something resembling the SDL API reference documentation, like this: https://wiki.libsdl.org/APIByCategory

 

 If anybody has any ideas as to how I could go about creating documentation in this fashion without having to hand-code the HTML (that was something I was considering at one point, and I'm plenty fluent in HTML/CSS, but it's just not something I feel I should have to do).. Documenting the scripting commands is enough work as it is.

 

 Suggestions please! Thanks!

Share this post


Link to post
Share on other sites
Advertisement
I always use a textual markup language to write documentation.

- restructuredtext (mostly for single file documents)
- sphinx (layer on top of restructuredtext, extending to big documentation sets), created for writing Python documentation (sphinx-doc.org, output at docs.python.org)
- markdown (github is best known example)
- asciidoc (eclipse switched to it, haven't yet worked with it)

There are probably a zillion other wiki-ish languages that can be useful to some extent

Other, more professional options are

- LaTeX aimed at writing books, also defacto standard for scientific publications (technical sciences at least), (results++)++, but it takes time to understand how to use it.
- word processors (no real experience with that)

Share this post


Link to post
Share on other sites
Probably one of the options above, or Bite the bullet and go straight HTML -- it shouldn't be that difficult if you create some skeletonized templates to fill in.

Or, you could create a more-specific markup of your own in XML and use xslt to transform it to html.

The benefit of that over markdown or similar is retaining semantic-based formatting. In markdown, bold is bold is bold, there's no way of retaining what was bolded because it was a keyword, or just because you wanted to emphasize that word. Retaining semantics gives you more flexibility of presentation and can help automate certain maintenance operations (e.g. Say you decide that keywords should be an italicized link instead of bold text). Consider whether the payoff would be worth the investment though.

If you do uses HTML, make sure to use CSS instead of inline styling or just sticking to built-in tags and default formatting.

Share this post


Link to post
Share on other sites
With a large enough language, you can start thinking towards Doxygen, and have the documentation source near the function definition in the source code, instead of in a separate document.
In its simplest form, it's just some text between "// start documentation" and "// end documentation" lines, that you extract from the source code, and insert in a document template.

If you have your own parser, you could do what Python has, if first statement is a string, it's the function documentation. You do need multi-line strings then to make it useful.

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!