Feature Request #291

jcom.hub autodoc function : possible optimization

Added by Julien Rabin about 12 years ago. Updated over 8 years ago.

Status:RejectedStart date:2009-08-19
Priority:NormalDue date:
Assignee:-% Done:

0%

Category:-Spent time:-
Target version:0.5.5
Branch:

Description

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.

jmod.syn.TESTER.html Magnifier - Demo html page (27.5 KB) Trond Lossius, 2010-02-03 10:15 am

jmod.syn.TEST2.html Magnifier (27.9 KB) Tom Stoll, 2010-02-05 12:38 am


Related issues

Copied to Max - Feature Request #1453: jcom.hub autodoc function : possible optimization Closed 2009-08-19

History

#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 ?

#3 Updated by Trond Lossius about 12 years ago

I second (or third) this...

Having them in the same file also makes it easier to search the page in a browser.

#4 Updated by Tim Place about 12 years ago

We could also conceal the common stuff, and then using some JavaScript/AJAX magic have it unfold from a disclosure triangle or something. That would keep in the same page, but hidden when not needed.

#5 Updated by Julien Rabin about 12 years ago

Tim Place wrote:

We could also conceal the common stuff, and then using some JavaScript/AJAX magic have it unfold from a disclosure triangle or something. That would keep in the same page, but hidden when not needed.

This sounds really great in my opinion!

#6 Updated by Tim Place almost 12 years ago

  • Target version changed from 0.5.1 to 0.5.2

#7 Updated by Trond Lossius over 11 years ago

Tom Stoll posted the following to the devel list, that should be taken into consideration:

Hi,

I've been playing around with some new html documentation that uses javascript to show and hide table rows. I'd like to get a sense of whether anyone thinks this is useful. I'm attaching a simple html file as an example. This is hacked from an HTML file that was automatically generated in the module. A few ideas/observations:

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?

=tms

  • 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

This newer version of the example checks each category against a list of default parameters/messages using JS. It would probably be better to back up one level and do this check in the autodoc code itself. In my example, a JS function makes 2 arrays (default and user) for the button to operate on. This could easily be accomplished in C by designating div classes, eliminating the redundancy of creating so much duplicate javascript.
I've also tweaked the css, and will continue to do so a little more, as well as test in various browsers/operating systems.

#10 Updated by Nils Peters over 9 years ago

  • Target version changed from 0.5.2 to 0.5.5

#11 Updated by Trond Lossius over 8 years ago

  • Status changed from New to Rejected

Also available in: Atom PDF