Feature Request #291
jcom.hub autodoc function : possible optimization
could it be possible that the html/maxref generated file separates common module's attributes/message/returns from the module's specifics ? IMHO this would make easier to read and get how the module works. A priori, I think of two possible options :
- having a formal distinction in the html/maxref file for the module's specific and common informations.
- having a link pointing to the common informations, for example similarly to the common box/matrix messages links used in maxref pages.
As for the ease of reading, I tend to prefer the second solution. However, although I did not check, I can think of some situations where it would not help (for example, modules not having a gain attribute). First solution could still be a nice little enhancement IMHO.
#1 Updated by Tim Place about 12 years ago
- Priority changed from Low to Normal
- Target version set to 0.5.1
I think this is a good idea. I was thinking about the same thing recently.
No matter how we present it, it requires that all 'subscribers' (parameters, messages, etc.) have a flag that indicates whether or not they are internal/common.
In terms of the presentation, I prefer to have everything on one page and hate the way you are required in Max's documentation to go looking for another page. One idea is that we could put all of the module-specific parameters/messages/returns in bold.
#2 Updated by Julien Rabin about 12 years ago
I am also not really fan of having the informations spread between two different files. The main advantage IMO is that it leaves less info in the module's help file to digest or to go thru when looking for a specific parameter/message/return. Maybe a compromise between these two solutions could be to first have a table(s) with specific p/m/r, then a second table(s) with common ones ?
#5 Updated by Julien Rabin about 12 years ago
Tim Place wrote:
This sounds really great in my opinion!
#7 Updated by Trond Lossius over 11 years ago
- File jmod.syn.TESTER.html added
Tom Stoll posted the following to the devel list, that should be taken into consideration:
1. This example is just the html. Getting the html files to be automatically generated would require an update to the backend, of course.
2. Basically what got me started on this was that I wanted to be able to hide the 'default' lines and focus on the functions that I created. In order for this to work, there's a more significant change that would have to be made: parameters/messages would have to be distinguishable and settable as default/User or some other attribute.
3. Perhaps there are other features that would be nice to include here as well? Hide-able columns? There definitely should be some attention paid to integration with the 'create-parameter/message' script that has recently appeared. ***
4. Perhaps someone else is already reworking the documentation, in which case what I'm playing around with is unnecessary?
- Which is broken, at least in the version that I'm looking at. Unless there is a fixed version out there that I should look for, I'll try to fix the script.
#8 Updated by Trond Lossius over 11 years ago
And Julien then replied:
Could there be a pure html/js solution rather than having to add a 'user defined' attribute to parameter/message/return source code ? For example, something like a js script doing 'if parameter name != (audio/mix OR audio/gain OR etc.) then class "user"; else class "default"' ? Not very elegant and optimized but maybe easier to implement in the mean time ? Just thinking out loud as I am not very experienced with html/js...
As for the status of the documentation, things are in progress so any suggestion is welcome of course.
#9 Updated by Tom Stoll over 11 years ago
- File jmod.syn.TEST2.html added
I've also tweaked the css, and will continue to do so a little more, as well as test in various browsers/operating systems.