add @doc_section("Wibble")

[inoas]

... to group docs into sections

• anything below is one section till the next section
• if not starting with a docsection int he module anything (but the 4x slash module doc) goes above sorted as before.
• per doc section the sorting would be as of now
• could support ## ### and to set h2 and h3?

[inoas]

... old habits die hard ref fubar.

[giacomocavalieri]

Maybe I'd start use the discussion forums to first talk about the design of such a feature.
As far as I'm aware we still haven't decided on how to do this exactly

[lpil]

I like this idea a lot but the details are not entirely clear to me.

I worry that having attributes as dividers would make them easy to make mistakes with. It's not immediately obvious what the previous and next sections are. Perhaps I am incorrect there. I've seen in Elm projects it's common to have comments like -- MODEL -------- and it seems to work OK for them.

One thing I like about the divider approach is that it makes it harder to have dangling uncategorised definitions than if each had to be individually annotated with an attribute.

If the attribute syntax is used it should be on some declaration rather than being a divider.

I could imagine it being desirable to have a way to add a header of markdown content to each section.

---

Using moduledocs

Perhaps the module doc syntax could be reused for this. At the top of the file it would be for the whole module, and then each one under that introduces a new section. A markdown heading could be used to name the section, though what we would do without a heading I am unsure.

//// The Wisp web framework

import gleam/list
... etc

//// # Requests
////
//// lorem ipsum...

pub fn require_method(
  request: HttpRequest(t),
  method: Method,
  next: fn() -> Response,
) -> Response {
  case request.method == method {
    True -> next()
    False -> method_not_allowed(allowed: [method])
  }
}

...

//// # Responses
////
//// lorem ipsum...

/// The body of a HTTP response, to be sent to the client.
///
pub type Body {
  Text(StringBuilder)
  Bytes(BytesBuilder)
  File(path: String)
  Empty
}

pub fn response(status: Int) -> Response {
  HttpResponse(status, [], Empty)
}

...

//// # Configuration
////
//// lorem ipsum...

pub fn set_max_body_size(request: Request, size: Int) -> Request {
  Connection(..request.body, max_body_size: size)
  |> request.set_body(request, _)
}

...

[lpil]

Roger.

Do you think that the ordering matters enough to warrant that flexibility? It's not something I think about myself, so good ot understand how others think.

How do you see the Elm section comments? What role to they serve?

[hayleigh-dot-dev]

I organise my code with those kinda section comments all over the place! I actually set up snippets for both elm and gleam to scaffold out a module like:

// CONSTANTS ---

// TYPES ---

// CONSTRUCTORS ---

// TRANSFORMATIONS ---

// CONVERSIONS ---

In the broadest of strokes, I like to organise my modules so that from a maintainer perspective they read top-to-bottom (or yaknow, as close to that as possible) and so those comments for me signpost sections relevant as a maintainer.

I think it is also true that some Elm devs use those section comments in a way that reflects the documented api ordering but I would say that that is just a happy coincidence that how they think about their code as an author aligns with how they want their code to be experienced as a user – something i dont think is always true.

[lpil]

Thank you.

[inoas]

I think we should keep maintainer and user order concistent. This also helps going from a user to a maintainer which is what many projects lack.

I too separate blocks like above. I just feel the alphabetical is the culprid because it removes an inherit association between things close to each other in source code, usually, if I have to reorder things so they belong to each other in both source code and generated documentation, that's fine to me.

[lpil]

This discussion does not include changing the ordering, only introducing grouping. Any changes from this discussion will keep it alphabetical