Style guide for automated api.txt?
- SonosFuer
- Member
- Posts: 104
- Joined: Sun Jul 09, 2017 00:32
- GitHub: apachano
- IRC: SonosFuer
- In-game: SonosFuer
Style guide for automated api.txt?
I want to propose a style guide for formatting api.txt files. I think it would be beneficial for the information to be able to be collected by a script then transferred into other resources such as collected api guides and resources for IDE's. What do you guys think?
Working on a content database for minetest mods, servers, and etc Check it out and give me feedback at viewtopic.php?f=14&t=18137
- Pyrollo
- Developer
- Posts: 385
- Joined: Mon Jan 08, 2018 15:14
- GitHub: pyrollo
- In-game: Naj
- Location: Paris
Re: Style guide for automated api.txt?
I think it could be good to keep compatible with documentation from source code systems like those ones :
http://lua-users.org/wiki/DocumentingLuaCode
http://lua-users.org/wiki/DocumentingLuaCode
[ Display Modpack ] - [ Digiterms ] - [ Crater MG ] - [ LATE ]
- ChimneySwift
- Member
- Posts: 320
- Joined: Fri Sep 22, 2017 06:46
- GitHub: ChimneySwift
- IRC: ChimneySwift
- In-game: ChimneySwift
- Location: 127.0.0.1
Re: Style guide for automated api.txt?
Is it just me or would it be beneficial to make it a .md file rather than a .txt file, as many text editors do syntax highlighting for markdown documents and GitHub shows them in a much easier to read format. I know I always change the file extension of files like this (eg, lua_api.txt). Obviously this is assuming they're written in markdown in the first place.
A spoon is basically a tiny bowl with a stick on it
- SonosFuer
- Member
- Posts: 104
- Joined: Sun Jul 09, 2017 00:32
- GitHub: apachano
- IRC: SonosFuer
- In-game: SonosFuer
Re: Style guide for automated api.txt?
Structuring in markdown could be beneficial but it could also provide issues with automation. If you want to automate pulling from the api file you need a specifically structured api file, almost as if it is code itself. You could do it but I feel like it would distract from the importance of machine readability when developers are filling it out.
You could also have an automated script take from the api file and print out a well formatted md file.
You could also have an automated script take from the api file and print out a well formatted md file.
Working on a content database for minetest mods, servers, and etc Check it out and give me feedback at viewtopic.php?f=14&t=18137
- rubenwardy
- Moderator
- Posts: 6972
- Joined: Tue Jun 12, 2012 18:11
- GitHub: rubenwardy
- IRC: rubenwardy
- In-game: rubenwardy
- Location: Bristol, United Kingdom
- Contact:
Re: Style guide for automated api.txt?
The file is already structured in MD form, it just isn't .MD as you then can't link to lines on github
Who is online
Users browsing this forum: No registered users and 10 guests