Option to not sort Enum values

[Jjagg]

DocFX Version Used: docfx 2.28.2.0

I'm letting docfx extract the metadata for my API reference from a .csproj. In the API reference all members are sorted. That's great, but I'd like enum values to stay in the original order as it makes more sense that way.

Is there currently a possible work around or extension to achieve this?

[vicancy]

makes sense. I think code change is needed. @vwxyzh Any idea?

[KristianWedberg]

I second this request. I was initially thinking of sorting on their numerical value, but having the original order would be much better.

[frankiDotNet]

Any changes here?
This looks like an usefull feature, also properties could have these option.

[vicancy]

Cc @herohua @superyyrrzz

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[KristianWedberg]

This would still be really useful, any chance it at least will be scheduled?

[superyyrrzz]

Sorry, it is not our current priority. However, this is a valid feature request that will not be marked as stale in the future.

[isJuhn]

Any updates for this?

[sebastienwarin]

Hello there,

You can do it easily with a few line of Javascript.

Create a extension for the preprocessor (see here) with the following code :

exports.postTransform = function (model) {

  if(model.isEnum) {

    var childrens = model.children[0].children;

    childrens.forEach(function (item) {
       const regex = /[\w\d]+\s?=\s?(\d+),?/gm;
       var m = regex.exec(item.syntax.content[0].value);
       if(m !== null) {
        item._enum_value = parseInt(m[1]); 
       }
    });

    const compare = function( a, b ) {
      if ( a._enum_value < b._enum_value ){
        return -1;
      }
      if ( a._enum_value > b._enum_value ){
        return 1;
      }
      return 0;
    }

    model.children[0].children = childrens.sort(compare);
  }

  return model;
}

I extract the "enum value" from the Syntax's content by using a regex and I set this value to the model. Then I can sort the enum values.

You can also display the "Enum value" in the "enum.tmpl.partial" :

  {{#children}}
    <tr>
      <td>{{_enum_value}}</td>
      <td id="{{id}}">{{name.0.value}}</td>  {{! or directly "syntax.content.0.value" }}      
      <td>{{{summary}}}</td>
    </tr>
  {{/children}}

Enjoy 👍

[JVemon]

The Javascript extension is good, but I do think this ought to be a docfx option. It's just more intuitive.

[dhymik]

This is not just a cosmetic issue. Often, enum values are used in < / > expressions, and order is important for understanding. This would be a great addition to have out of the box.

[Alan-FGR]

Can somebody detail the steps required for the custom JS plugin to work? I've tried adding the files in my custom template to no avail, not sure how DocFX is supposed to discover them but apparently it's not a matter of just placing them there. Thanks

[curtspiteri]

Any updates on this please?
Also I suggest to have the option to NOT order/sort anywhere (i.e. even classes not just Enums) since sometimes there can be situations where fields/properties are put in a specific order on purpose and thus should reflect the order how they were developed even in documentation.

[KalleOlaviNiemitalo]

Years ago, I used Sandcastle to generate API docs for a C++/CLI project. It turned out that the C++/CLI compiler shuffled the order of enum constants in the ECMA-335 metadata so that it did not match the lexical order of declarations, the alphabetic order of names, nor the numeric order of values. I don't know whether the C# compiler is more predictable in this respect, or whether the deterministic compilation option affects this.